|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.didisoft.pgp.bc.elgamal.security.Cipher
public abstract class Cipher
This class is used to provide the functionality of a general purpose encryption algorithm, such as DES or RSA. Encryption is used to ensure confidentiality of digital data.
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.9 $
Field Summary | |
---|---|
static int |
DECRYPT
The state of the cipher when it is ready to decrypt, that is, the state it is in right after a call to initDecrypt . |
static int |
ENCRYPT
The state of the cipher when it is ready to encrypt, that is, the state it is in right after a call to initEncrypt . |
static int |
UNINITIALIZED
The state of the cipher object when it is uninitialized, that is, the state it is in right after it has been created. |
Method Summary | |
---|---|
int |
blockSize()
Returns the length of a block for this cipher. |
java.lang.Object |
clone()
Returns a clone of this cipher. |
byte[] |
crypt(byte[] in)
Encrypts or decrypts the specified array of data, which will be automatically padded/unpadded as necessary. |
byte[] |
crypt(byte[] in,
int offset,
int length)
Encrypts or decrypts the specified array of data, which will be automatically padded/unpadded as necessary. |
int |
crypt(byte[] in,
int inOffset,
int inLen,
byte[] out,
int outOffset)
Encrypts or decrypts the specified subarray of data, pads or unpads it as necessary, and places the result in the specified output buffer. |
byte[] |
doFinal(byte[] in)
Equivalent to crypt(in) . |
byte[] |
doFinal(byte[] in,
int offset,
int length)
Equivalent to crypt(in, offset, length) . |
int |
doFinal(byte[] in,
int inOffset,
int inLen,
byte[] out)
Equivalent to crypt(in, inOffset, inLen, out, 0) . |
int |
doFinal(byte[] in,
int inOffset,
int inLen,
byte[] out,
int outOffset)
Equivalent to crypt(in, inOffset, inLen, out, outOffset) . |
java.lang.String |
getAlgorithm()
Returns this algorithm's standard cipher name (not including mode and padding). |
static java.lang.String[] |
getAlgorithms()
Gets the standard names of all Ciphers implemented by any installed provider. |
static java.lang.String[] |
getAlgorithms(java.security.Provider provider)
Gets the standard names of all Ciphers implemented by a provider. |
int |
getCiphertextBlockSize()
Returns the length of a ciphertext block, in bytes. |
int |
getInputBlockSize()
Returns the length of an input block, in bytes. |
static Cipher |
getInstance(Cipher cipher,
com.didisoft.pgp.bc.elgamal.security.Mode mode,
com.didisoft.pgp.bc.elgamal.security.PaddingScheme padding)
Generates a new Cipher object by composing the given Cipher, Mode and PaddingScheme objects. |
static Cipher |
getInstance(java.lang.String algorithm)
Generates a Cipher object that implements the given algorithm. |
static Cipher |
getInstance(java.lang.String algorithm,
java.lang.String provider)
Generates a Cipher object that implements the given cipher, from the given provider. |
java.lang.String |
getMode()
Returns this algorithm's standard mode name. |
int |
getOutputBlockSize()
Returns the length of an output block, in bytes. |
java.lang.String |
getPadding()
Returns this algorithm's standard padding scheme name. |
java.lang.Object |
getParameter(java.lang.String param)
Gets the value of the specified algorithm parameter. |
int |
getPlaintextBlockSize()
Returns the length of a plaintext block, in bytes. |
java.lang.String |
getProvider()
Returns the name of the provider of this cipher. |
int |
getState()
Returns the state of this Cipher object. |
int |
inBufferSize(int outLen)
Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to update (i.e. |
int |
inBufferSizeFinal(int outLen)
Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to crypt
(including padding for the final block of the stream, if applicable). |
void |
initDecrypt(java.security.Key key)
Initializes this cipher for decryption, using the specified key. |
void |
initEncrypt(java.security.Key key)
Initializes this cipher for encryption, using the specified key. |
boolean |
isPaddingBlockCipher()
Returns true if this cipher is a padding block cipher. |
int |
outBufferSize(int inLen)
Returns the size of the buffer necessary to hold the output resulting from a call to update (i.e. |
int |
outBufferSizeFinal(int inLen)
Returns the size of the buffer necessary to hold the output resulting from a call to crypt (including padding
for the final block of the stream, if applicable). |
void |
setParameter(java.lang.String param,
java.lang.Object value)
Sets the specified algorithm parameter to the specified value. |
java.lang.String |
toString()
|
byte[] |
update(byte[] in)
Encrypts or decrypts the specified array of data, which is not the final data in this stream. |
byte[] |
update(byte[] in,
int offset,
int length)
Encrypts or decrypts the specified subarray of data, which is not the final data in this stream. |
int |
update(byte[] in,
int inOffset,
int inLen,
byte[] out)
Encrypts or decrypts the specified subarray of data, which is not the final data in this stream, and places the result in the specified output buffer (starting at offset 0). |
int |
update(byte[] in,
int inOffset,
int inLen,
byte[] out,
int outOffset)
Encrypts or decrypts the specified subarray of data, which is not the final data in this stream, and places the result in the specified output buffer. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int UNINITIALIZED
public static final int ENCRYPT
initEncrypt
.
initEncrypt(java.security.Key)
,
Constant Field Valuespublic static final int DECRYPT
initDecrypt
.
initDecrypt(java.security.Key)
,
Constant Field ValuesMethod Detail |
---|
public static Cipher getInstance(java.lang.String algorithm) throws java.security.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.
algorithm
- the algorithm name, as described above.
java.security.NoSuchAlgorithmException
- if the algorithm is
not available from any provider.public static Cipher getInstance(java.lang.String algorithm, java.lang.String provider) throws java.security.NoSuchAlgorithmException, java.security.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.
algorithm
- the cipher specification.
java.security.NoSuchAlgorithmException
- if the algorithm is not
available from the provider.
java.security.NoSuchProviderException
- if the provider is not
available in the environment.public static Cipher getInstance(Cipher cipher, com.didisoft.pgp.bc.elgamal.security.Mode mode, com.didisoft.pgp.bc.elgamal.security.PaddingScheme padding)
This method is not supported in JavaSoft's version of JCE.
java.lang.NullPointerException
- if cipher == nullpublic final int getState()
UNINITIALIZED
,
ENCRYPT
,
DECRYPT
public final java.lang.String getAlgorithm()
See International JCE Standard Algorithm Names for a list of Cipher algorithm names.
public final java.lang.String getMode()
See International JCE Standard Algorithm Names for a list of Mode algorithm names.
public final java.lang.String getPadding()
See International JCE Standard Algorithm Names for a list of PaddingScheme algorithm names.
public final java.lang.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.
inLen
- the number of bytes to process.
java.lang.IllegalArgumentException
- if inLen < 0public 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.
inLen
- the number of bytes to process.
java.lang.IllegalArgumentException
- if inLen < 0public 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.
outLen
- the number of bytes of output required.
java.lang.IllegalArgumentException
- if outLen < 0public 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.
outLen
- the number of bytes of output required.
java.lang.IllegalArgumentException
- if outLen < 0public final int blockSize()
IllegalBlockSizeException
- if getPlaintextBlockSize() !=
getCiphertextBlockSize()public final int getInputBlockSize()
This method is not supported in JavaSoft's version of JCE.
java.lang.Error
- if the cipher is uninitialized.public final int getOutputBlockSize()
This method is not supported in JavaSoft's version of JCE.
java.lang.Error
- if the cipher is uninitialized.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(java.security.Key key) throws java.security.KeyException
key
- the key to use for encryption.
java.lang.NullPointerException
- if key == null
java.security.KeyException
- if the key is invalid.public final void initDecrypt(java.security.Key key) throws java.security.KeyException
key
- the key to use for decryption.
java.lang.NullPointerException
- if key == null
java.security.KeyException
- if the key is invalid.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.
in
- the input data.
java.lang.NullPointerException
- if in == nullpublic 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.
in
- the input data.offset
- the offset indicating where the subarray starts in the
in array.length
- the length of the subarray.
java.lang.NullPointerException
- if in == null
java.lang.IllegalArgumentException
- if length < 0
java.lang.ArrayIndexOutOfBoundsException
- if offset < 0 ||
(long) offset + length > in.lengthpublic 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.
in
- the input data.inOffset
- the offset indicating where the subarray starts in
the in array.inLen
- the length of the subarray.out
- the output buffer.
java.lang.NullPointerException
- if in == null || out == null
java.lang.IllegalArgumentException
- if inLen < 0
java.lang.ArrayIndexOutOfBoundsException
- if inOffset < 0 ||
outOffset < 0 || (long) inOffset + inLen > in.length ||
outBufferSize(inLen) > out.lengthpublic 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.
in
- the input data.inOffset
- the offset indicating where the subarray starts in
the in array.inLen
- the length of the subarray.out
- the output buffer.outOffset
- the offset indicating where to start writing the
result into the output buffer.
java.lang.NullPointerException
- if in == null || out == null
java.lang.IllegalArgumentException
- if inLen < 0
java.lang.ArrayIndexOutOfBoundsException
- if inOffset < 0 ||
outOffset < 0 || (long) inOffset + inLen > in.length ||
(long) outOffset + outBufferSize(inLen) > out.lengthpublic 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.
in
- the input data.
java.lang.NullPointerException
- if in == null
IllegalBlockSizeException
- if the final block cannot be
padded or unpadded.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.
in
- the input data.offset
- the offset indicating where the subarray starts in the
in array.length
- the length of the subarray.
java.lang.NullPointerException
- if in == null
java.lang.IllegalArgumentException
- if length < 0
java.lang.ArrayIndexOutOfBoundsException
- if offset < 0 ||
(long) offset + length > in.length
IllegalBlockSizeException
- if the final block cannot be padded
or unpadded.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.
in
- the input data.inOffset
- the offset indicating where the subarray starts in
the in array.inLen
- the length of the subarray.out
- the output buffer.outOffset
- the offset indicating where to start writing the
result into the output buffer.
java.lang.NullPointerException
- if in == null || out == null
java.lang.IllegalArgumentException
- if inLen < 0
java.lang.ArrayIndexOutOfBoundsException
- if inOffset < 0 ||
outOffset < 0 || (long) inOffset + inLen > in.length ||
(long) outOffset + outBufferSize(inLen) > out.length
IllegalBlockSizeException
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.
IllegalBlockSizeException
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.
IllegalBlockSizeException
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.
IllegalBlockSizeException
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.
IllegalBlockSizeException
public void setParameter(java.lang.String param, java.lang.Object value) throws NoSuchParameterException, java.security.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.
setParameter
in interface Parameterized
param
- the string identifier of the parameter.value
- the parameter value.
java.lang.NullPointerException
- if param == null
NoSuchParameterException
- if there is no parameter with name
param for this cipher implementation.
java.security.InvalidParameterException
- if the parameter exists but cannot
be set (for example because the cipher is in the
wrong state).
InvalidParameterTypeException
- if value is the wrong type
for this parameter.public java.lang.Object getParameter(java.lang.String param) throws NoSuchParameterException, java.security.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.
getParameter
in interface Parameterized
param
- the string name of the parameter.
java.lang.NullPointerException
- if param == null
NoSuchParameterException
- if there is no parameter with name
param for this cipher implementation.
java.security.InvalidParameterException
- if the parameter exists but cannot
be read.public java.lang.Object clone() throws java.lang.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.
clone
in class java.lang.Object
java.lang.CloneNotSupportedException
- if the cipher is not cloneable.public java.lang.String toString()
toString
in class java.lang.Object
public static java.lang.String[] getAlgorithms(java.security.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 java.lang.String[] getAlgorithms()
This method
is not supported in JavaSoft's version of JCE.
For compatibility you may wish to use
IJCE.getAlgorithms("Cipher")
instead.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |