All Packages Class Hierarchy This Package Previous Next Index
java.lang.Object
|
+----java.security.IJCE_Traceable
|
+----java.security.Cipher
This class follows the general algorithm architecture found elsewhere in the security API: the base class provides an algorithm-independent interface to basic encryption functionality, with provider implementation subclassing a subset of the behaviours.
Like other algorithm-based classes in Java Security, the Cipher class is separated between application and provider interfaces:
engine. Each such method is
usually called by a correspondingly-named public API method.
For example, the engineInitEncrypt method is
called by the initEncrypt method.
Ciphers represented by this class satisfy the following constraints:
Byte-oriented stream ciphers (or ciphers in CFB and OFB modes, for example) have plaintext and ciphertext block sizes of 1 byte. For public key ciphers, it is common for the block sizes to be dependent on the length of some parameter of the public key.
A block cipher implementation may either implement its own buffering
(by passing implBuffering == true to the constructor), or leave
it to the Cipher superclass (implBuffering == false). When
the implementation handles buffering, data passed to update is
passed directly on to engineUpdate, and data passed to
crypt is passed to engineUpdate, followed
immediately by a call to engineCrypt.
When the Cipher superclass handles buffering, up to one block is buffered,
in order to ensure that the length of data passed to engineUpdate
is always a multiple of the block size. In this case the engineCrypt
method is not used.
Cipher implementations are not required or expected to be threadsafe. If methods of a single Cipher object are called simultaneously by more than one thread, the result will be unpredictable.
Copyright © 1997
Systemics Ltd on behalf of the
Cryptix Development Team.
All rights reserved.
$Revision: 1.8 $
initDecrypt.
initEncrypt.
crypt(in).
crypt(in, offset, length).
crypt(in, inOffset, inLen, out, 0).
crypt(in, inOffset, inLen, out, outOffset).
engineUpdate (when isFinal is false), or
successive calls to both engineUpdate and
engineCrypt (when isFinal is true).
update (i.e.
crypt
(including padding for the final block of the stream, if applicable).
update (i.e.
crypt (including padding
for the final block of the stream, if applicable).
public static final int UNINITIALIZED
public static final int ENCRYPT
initEncrypt.
public static final int DECRYPT
initDecrypt.
protected Cipher()
protected Cipher(boolean implBuffering,
boolean implPadding,
String provider)
For byte-oriented stream ciphers (where the input block size is 1), buffering is not needed, and the implBuffering parameter has no effect.
protected Cipher(boolean implBuffering,
String provider,
String algorithm)
This constructor is not supported in JavaSoft's version of JCE.
protected final PaddingScheme getPaddingScheme()
public static Cipher getInstance(String algorithm) throws NoSuchAlgorithmException
Any of the following formats can be used for the algorithm name:
See International JCE Standard Algorithm Names for a list of Cipher algorithm names.
public static Cipher getInstance(String algorithm,
String provider) throws NoSuchAlgorithmException, NoSuchProviderException
getInstance(String algorithm).
If the algorithm is implemented using more than one component
(cipher, mode, and padding scheme), all of them must come from the
given provider. More flexibility can be obtained by using the
getInstance(Cipher, Mode, PaddingScheme) factory method.
For example, to request "DES" from the SUN provider, "CBC" from the
Cryptix provider, and "PKCS#5" from any provider, use:
Cipher.getInstance(
Cipher.getInstance("DES", "SUN"),
Mode.getInstance("CBC", "Cryptix"),
PaddingScheme.getInstance("PKCS#5")
)
See International JCE Standard Algorithm Names for a list of Cipher algorithm names.
public static Cipher getInstance(Cipher cipher,
Mode mode,
PaddingScheme padding)
This method is not supported in JavaSoft's version of JCE.
public final int getState()
public final String getAlgorithm()
See International JCE Standard Algorithm Names for a list of Cipher algorithm names.
public final String getMode()
See International JCE Standard Algorithm Names for a list of Mode algorithm names.
public final String getPadding()
See International JCE Standard Algorithm Names for a list of PaddingScheme algorithm names.
public final String getProvider()
public final boolean isPaddingBlockCipher()
A cipher is a padding block cipher iff getPlaintextBlockSize() > 1
&& getPaddingScheme() != null.
If getPlaintextBlockSize throws an exception, so will this method.
This method is needed because CipherInputStream and CipherOutputStream use a different buffering algorithm for padding block ciphers.
This method is not supported in JavaSoft's version of JCE.
public final int outBufferSize(int inLen)
update (i.e. not including
padding). This call takes into account any incomplete block
currently being buffered.
public final int outBufferSizeFinal(int inLen)
crypt (including padding
for the final block of the stream, if applicable). This call takes
into account any incomplete block currently being buffered.
This method is not supported in JavaSoft's version of JCE.
public final int inBufferSize(int outLen)
update (i.e.
not including padding). This call takes into account any incomplete
block currently being buffered.
This is used by CipherInputStream, for example, to calculate how much data must be read from its underlying stream before encryption or decryption.
This method is not supported in JavaSoft's version of JCE.
public final int inBufferSizeFinal(int outLen)
crypt
(including padding for the final block of the stream, if applicable).
This call takes into account any incomplete block currently being
buffered.
This method is not supported in JavaSoft's version of JCE.
public final int blockSize()
public final int getInputBlockSize()
This method is not supported in JavaSoft's version of JCE.
public final int getOutputBlockSize()
This method is not supported in JavaSoft's version of JCE.
public final int getPlaintextBlockSize()
This method is not supported in JavaSoft's version of JCE.
public final int getCiphertextBlockSize()
This method is not supported in JavaSoft's version of JCE.
public final void initEncrypt(Key key) throws KeyException
public final void initDecrypt(Key key) throws KeyException
public final byte[] update(byte in[])
update or crypt.
Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public final byte[] update(byte in[],
int offset,
int length)
update or crypt.
Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public final int update(byte in[],
int inOffset,
int inLen,
byte out[])
update or crypt.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. out.length must be at least
outBufferSize(inLen), otherwise an
ArrayIndexOutOfBoundsException will be thrown (in this case it is
not specified how much, if any, of the output will have been written).
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public final int update(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset)
update or crypt.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. out.length must be at least
(long) outOffset + outBufferSize(inLen), otherwise an
ArrayIndexOutOfBoundsException will be thrown (in this case it is
not specified how much, if any, of the output will have been written).
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public final byte[] crypt(byte in[]) throws IllegalBlockSizeException
Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.
If the final block is incomplete, the cipher must have a padding scheme other than "NONE", and it must be in the ENCRYPT state. If this is not the case, an IllegalBlockSizeException will be thrown.
If the cipher is in the DECRYPT state and padding is being used,
at least one full ciphertext block should be passed to crypt.
This is necessary because the last block contains information needed to
determine the length of the original plaintext.
public final byte[] crypt(byte in[],
int offset,
int length) throws IllegalBlockSizeException
Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.
If the final block is incomplete, the cipher must have a padding scheme other than "NONE", and it must be in the ENCRYPT state. If this is not the case, an IllegalBlockSizeException will be thrown.
If the cipher is in the DECRYPT state and padding is being used,
at least one full ciphertext block should be passed to crypt.
This is necessary because the last block contains information needed to
determine the length of the original plaintext.
public final int crypt(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset) throws IllegalBlockSizeException
Whether the data is encrypted or decrypted depends on the cipher's initialization state.
If the final block is incomplete, the cipher must have a padding scheme other than "NONE", and it must be in the ENCRYPT state. If this is not the case, an IllegalBlockSizeException will be thrown.
If the cipher is in the DECRYPT state and padding is being used,
at least one full ciphertext block should be passed to crypt.
This is necessary because the last block contains information needed to
determine the length of the original plaintext.
public final byte[] doFinal(byte in[]) throws IllegalBlockSizeException
crypt(in).
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public final byte[] doFinal(byte in[],
int offset,
int length) throws IllegalBlockSizeException
crypt(in, offset, length).
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public final int doFinal(byte in[],
int inOffset,
int inLen,
byte out[]) throws IllegalBlockSizeException
crypt(in, inOffset, inLen, out, 0).
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public final int doFinal(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset) throws IllegalBlockSizeException
crypt(in, inOffset, inLen, out, outOffset).
This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for javax.crypto.Cipher.
public void setParameter(String param,
Object value) throws NoSuchParameterException, InvalidParameterException, InvalidParameterTypeException
This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.
This method is not supported in JavaSoft's version of JCE.
public Object getParameter(String param) throws NoSuchParameterException, InvalidParameterException
This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.
This method is not supported in JavaSoft's version of JCE.
public Object clone() throws CloneNotSupportedException
Note: In JavaSoft's version of JCE, Cipher.clone() is
protected. This is not very useful, since then an application (as opposed
to the cipher implementation itself) is not able to call it.
public String toString()
protected void engineSetPaddingScheme(PaddingScheme padding)
Cipher implementations may override this method in order to be notified
when the padding scheme is set (in this case they should always call
super.engineSetPaddingScheme(padding)). Normally, overriding
this method is not required.
protected int engineBlockSize()
The value may change when initEncrypt or
initDecrypt is called, but it should not change at
other times.
protected int enginePlaintextBlockSize()
The value may change when initEncrypt or
initDecrypt is called, but it should not change at
other times.
The default implementation returns engineBlockSize().
protected int engineCiphertextBlockSize()
The value may change when initEncrypt or
initDecrypt is called, but it should not change at
other times.
The default implementation returns engineBlockSize().
protected int engineOutBufferSize(int inLen,
boolean isFinal)
isFinal is true when this
is the final block of input.
If implBuffering is false, the inLen
parameter already takes into account the length of any required
padding, and buffered data. In this case inLen will be
a multiple of the input block size (this may only be true for IJCE,
not for other implementations of JCE).
The default implementation assumes that the output will have the
same number of blocks as the input (i.e. the result is
inLen / getInputBlockSize() * getOutputBlockSize()).
You will need to override this method if the cipher handles its own buffering.
protected int engineInBufferSize(int outLen,
boolean isFinal)
engineUpdate (when isFinal is false), or
successive calls to both engineUpdate and
engineCrypt (when isFinal is true).
If implBuffering is false, this method need not take
into account padding or buffered data when calculating the result.
In this case outLen will be a multiple of the output
block size (this may only be true for IJCE, not for other
implementations of JCE).
The default implementation assumes that the output will have the
same number of blocks as the input (i.e. the result is
outLen / getOutputBlockSize() * getInputBlockSize()).
You will need to override this method if the cipher handles its own buffering.
protected abstract void engineInitEncrypt(Key key) throws KeyException
After a call to this method, the cipher's state is set to ENCRYPT.
protected abstract void engineInitDecrypt(Key key) throws KeyException
After a call to this method, the cipher's state is set to DECRYPT.
protected abstract int engineUpdate(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset)
When implBuffering is true, this method will be called
with the same data that is passed to update or
crypt (i.e. there will be exactly one call to
engineUpdate for each call to update or
crypt).
When implBuffering is false, the Cipher superclass will
ensure that when it calls this method, inLen is a non-negative
multiple of getInputBlockSize().
in and out may be the same array, and the input and output regions may overlap. A cipher implementation should not use any part of in or out as working storage for intermediate steps of the algorithm. It should copy only the final result into the out array.
SECURITY: if array arguments are passed to native code, the implementation must ensure that a buffer overflow or illegal memory access cannot occur, regardless of the arguments passed to this method. I.e. the native library should not be called if:
in == null || out == null || inLen < 0 || inLen % (block size) != 0 || inOffset < 0 || (long)inOffset + inLen > in.length || outOffset < 0 || (long)outOffset + (number of bytes to be written) > out.length
Note that the (long) casts are essential, because
inOffset or outOffset could be close to
Integer.MAX_VALUE. The native method being called
should be private. This is important because untrusted code could
subclass the cipher implementation, and call this method directly
with any arguments.
protected int engineCrypt(byte out[],
int outOffset)
This method is overriden by ciphers that handle their own buffering
(i.e. implBuffering == true). It should flush the internal
buffer, and process any remaining data. By default, this method
returns 0.
Ciphers that pass implBuffering == false to the superclass
constructor need not override this method.
SECURITY: if array arguments are passed to native code, the implementation must ensure that a buffer overflow or illegal memory access cannot occur, regardless of the arguments passed to this method. I.e. the native library should not be called if:
out == null || outOffset < 0 || (long)outOffset + (number of bytes to be written) > out.length
Note that the (long) cast is essential, because
outOffset could be close to Integer.MAX_VALUE.
The native method being called should be private. This is important
because untrusted code could subclass the cipher implementation, and
call this method directly with any arguments.
protected void engineSetParameter(String param,
Object value) throws NoSuchParameterException, InvalidParameterException, InvalidParameterTypeException
This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.
The default implementation always throws a NoSuchParameterException.
This method is not supported in JavaSoft's version of JCE.
protected Object engineGetParameter(String param) throws NoSuchParameterException, InvalidParameterException
This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.
The default implementation always throws a NoSuchParameterException.
This method is not supported in JavaSoft's version of JCE.
public static String[] getAlgorithms(Provider provider)
This method
is not supported in JavaSoft's version of JCE.
For compatibility you may wish to use
IJCE.getAlgorithms(provider, "Cipher") instead.
public static String[] getAlgorithms()
This method
is not supported in JavaSoft's version of JCE.
For compatibility you may wish to use
IJCE.getAlgorithms("Cipher") instead.
All Packages Class Hierarchy This Package Previous Next Index