|
Oracle Security Developer Tools Crypto Java API Reference 10g (10.1.4.0.1) B28171-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
oracle.security.crypto.core.Coder
oracle.security.crypto.core.Cipher
A generic class for representing Ciphers, which may be BlockCiphers or direct descendants of the Cipher class.
While it is possible to instantiate a Cipher implemetation directly, the static factory methods included in the Cipher class are preferred. To use these methods, the user will need to provide an AlgorithmIdentifier
, which specifies an algorithm (such as DES in ECB mode) by its OID (Object ID), as well as any additional parameters the algorithm may require to configure itself (such as initialization vectors for CBC mode).
Because AlgorithmIdentifiers are integral to the correct use of Ciphers and to representing the identity and parameters of an algorithm, the AlgID
interface is provided which contains a reference instance of each AlgorithmIdentifier supported in the Phaos Security Engine.
For example, to get an initialized instance of a DES Cipher in ECB (electronic code book) mode that uses no padding and a randomly generated key, the following code might be used:
SymmetricKeyGenerator generator = SymmetricKeyGenerator.getInstance(AlgID.desECB);
SymmetricKey key = generator.generateKey();
Cipher desCipher = Cipher.getInstance(AlgID.desECB, key);
At this point the Cipher instance desCipher
is ready to be used for either encryption or decryption (of course, decrypting with a random key is not meaningful).
A more common use case for BlockCiphers involves the use of CBC (cipher block chaining) mode, which requires an Initialization Vector (IV). Because IV's do not need to be hidden or have any special values in order to provide an increased level of security in CBC mode, they are generally randomly generated before encryption. Phaos Security Engine BlockCiphers are designed to generate a random IV when they are initialized into CBC mode but aren't provided with an IV. So, the code example above could be used to create a DES instance in CBC mode by merely substituting AlgID.desCBC
for AlgID.desECB
.
In cases where decryption (or encryption) must be peformed with a given IV, the CBCAlgorithmIdentifier
class can be used to pass the IV to the Cipher as a parameter of the AlgorhithmIdentifier
. The following code shows how a BlockCipher instance may be obtained that uses CBC mode with a known IV, and that uses PKCS#5 block padding:
// byte[] iv is already instantiated as an IV that has length equal
// to the Block Size of DES(8 bytes).
CBCAlgorithmIdentifier cbcAlgID = new CBCAlgorithmIdentifier(AlgID.desCBC, iv);
SymmetricKeyGenerator generator = SymmetricKeyGenerator.getInstance(AlgID.desCBC);
SymmetricKey key = generator.generateKey();
Cipher desCipher = Cipher.getInstance(cbcAlgID, key, Padding.PKCS5);
Finally, when using a Cipher, it is important to keep a few rules in mind:
Field Summary | |
static int |
CBC Cipher Block Chaining (CBC) mode. |
protected Key |
decryptionKey Deprecated. No replacement. |
static int |
ECB Electronic Code Book (ECB) mode (default). |
protected Key |
encryptionKey Deprecated. No replacement. |
protected Key |
key Internal key reference that is used by the cipher for either encryption or decryption operations(depending on which one is performed first). |
protected int |
mode Flags the block Mode that the Cipher is operating in. |
static int |
NULL_PADDING Deprecated. Use the Padding class constants instead. |
static int |
PKCS5_PADDING Deprecated. Use the Padding class constants instead. |
protected RandomBitsSource |
rbs RandomBitsSource the Cipher might use during its operation. |
Constructor Summary | |
protected |
Cipher() |
Method Summary | |
protected void |
assertDecryption() Used by subclasses to lock the cipher into Decryption mode. |
protected void |
assertEncryption() Used by subclasses to lock the cipher into Encryption mode. |
abstract int |
blockSize() Deprecated. Use getBlockSize() instead. |
Key |
cloneKey() Returns a clone of the Key held by the Cipher. |
byte[] |
decodeOp(byte[] input) Decrypts an array of bytes by calling Cipher.decrypt(byte[]); This implements the Coder interface. |
byte[] |
decrypt(byte[] input) Decrypts an entire array of bytes and returns the original plaintext message. |
byte[] |
decrypt(byte[] bytes, boolean unpad) Decrypts an entire array of bytes and, if specified, unpads the result. |
byte[] |
decrypt(byte[] input, int inOff, int len) Decrypts a sequence of bytes of specified length and returns the original plaintext message. |
abstract byte[] |
decrypt(byte[] input, int inOff, int len, boolean unpad) Decrypts a sequence of bytes of specified length, and, if specified, returns the unpadded plaintext. |
abstract void |
decrypt(byte[] input, int inOff, int len, byte[] output, int outOff) Decrypts a sequence of bytes of specified length and places the original plaintext message in the given output buffer starting at the given offset. |
byte[] |
decryptOp(byte[] bytes) Deprecated. Use a decrypt method instead. |
abstract void |
decryptOp(byte[] in, int inOff, byte[] out, int outOff) Deprecated. Use a decrypt method instead. |
byte[] |
encodeOp(byte[] input) Encrypts an array of bytes by calling Cipher.encrypt(byte[]); . |
byte[] |
encrypt(byte[] input) Encrypts an entire array of bytes. |
byte[] |
encrypt(byte[] bytes, boolean pad) Encrypts an entire array of bytes and, if specified, performs padding. |
byte[] |
encrypt(byte[] input, int inOff, int len) Encrypts a sequence of bytes of specified length. |
abstract byte[] |
encrypt(byte[] input, int inOff, int len, boolean pad) Encrypts a sequence of bytes of specified length and, if specified, performs padding. |
abstract void |
encrypt(byte[] input, int inOff, int len, byte[] output, int outOff) Encrypts a sequence of bytes of specified length and places the resulting ciphertext in the given output buffer starting at the given offset. |
byte[] |
encryptOp(byte[] bytes) Deprecated. Use an encrypt method instead. |
abstract void |
encryptOp(byte[] in, int inOff, byte[] out, int outOff) Deprecated. Use an encrypt method instead. |
void |
erase() Erases any sensitive information (such as buffers and subkey tables) stored in this cipher object. |
abstract AlgorithmIdentifier |
getAlgID() Builds an AlgorithmIdentifier that is a "snapshot" of the Cipher's current configuration. |
abstract int |
getBlockSize() Returns the block size of the cipher, or 0 if the cipher is not a BlockCipher. |
Key |
getDecryptionKey() Deprecated. Use cloneKey() instead. |
Key |
getEncryptionKey() Deprecated. Use cloneKey() instead. |
static Cipher |
getInstance(AlgorithmIdentifier algID) Deprecated. Use a getInstance() method that returns an initialized cipher instead. |
static Cipher |
getInstance(AlgorithmIdentifier algID, Key key) Returns an initialized instance of a Cipher based on an AlgorithmIdentifier's Object ID. |
static Cipher |
getInstance(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID) Returns an initialized instance of a BlockCipher based on an AlgorithmIdentifier's Object ID. |
static Cipher |
getInstance(PrivateKey key) Returns an initialized instance of the cipher based on the Object ID of the AlgorithmIdentifier contained by the parameter Key. |
static Cipher |
getInstance(PublicKey key) Returns an initialized instance of the cipher based on the Object ID of the AlgorithmIdentifier contained by the parameter Key. |
byte[] |
getIV() Returns a clone of the initialization vector that was used by the Cipher instance, or null if the Cipher does not use an initialiation vector. |
SymmetricKey |
getKey() Deprecated. Use cloneKey() instead. |
int |
getMode() Returns the block mode used by this cipher. |
int |
getPadding() Deprecated. Use getPaddingID() instead. |
Padding.ID |
getPaddingID() Gets the ID of the Padding used by the Cipher. |
abstract void |
initialize(AlgorithmIdentifier algID, Key key) This method verifies the AlgorithmIdentifier's Object ID and configures the Cipher appropriately with the params of the AlgorithmIdentifier in addition to the Key. |
void |
initialize(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID) This method may be used to initialize a BlockCipher with the given algorithm parameters, symmetric key, and padding descriptor. |
byte[] |
pad(byte[] bytes) Deprecated. No replacement. |
protected void |
releaseOp() Used by subclasses to release the Cipher instance for use by another operation. |
abstract void |
setAlgID(AlgorithmIdentifier algID) Deprecated. Use an initialize method. |
void |
setDecryptionKey(Key key) Deprecated. Use an initialize method instead. |
void |
setEncryptionKey(Key key) Deprecated. Use an initialize method instead. |
void |
setIV(byte[] iv) Deprecated. Use an initialize method. |
void |
setKey(SymmetricKey key) Deprecated. Use an initialize method instead. |
void |
setMode(int mode) Deprecated. Use an initialize method. |
void |
setPadding(int padding) Deprecated. Use an initialize method. |
void |
setRandomBitsSource(RandomBitsSource rbs) Deprecated. |
byte[] |
unpad(byte[] bytes) Deprecated. No replacement. |
Methods inherited from class oracle.security.crypto.core.Coder |
algName, decode, decode, encode, encode, initialize |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
protected int mode
protected Key encryptionKey
protected Key decryptionKey
protected Key key
protected RandomBitsSource rbs
public static final int NULL_PADDING
Padding
class constants instead.public static final int PKCS5_PADDING
Padding
class constants instead.public static final int ECB
public static final int CBC
Constructor Detail |
protected Cipher()
Method Detail |
public static Cipher getInstance(AlgorithmIdentifier algID) throws AlgorithmIdentifierException
The resulting instance must still be initialized.
algID
- is the AlgorithmIdentifier whose ASN1ObjectID will be used to locate an appropriate Cipher instance.AlgorithmIdentifierException
- is thrown if no suitable Cipher can be found for the given AlgorithmIdentifier or if there is a problem initializing the Cipher instance with the given AlgorithmIdentifier.public static Cipher getInstance(AlgorithmIdentifier algID, Key key) throws AlgorithmIdentifierException, InvalidKeyException, CipherException
The resulting instance has been initialized with the given Key, AlgorithmIdentifer and no RandomBitsSource because the Cipher will load the default RandomBitsSource if it is required.
algID
- is the AlgorithmIdentifier whose params will be used to configure the cipher.key
- is the Key instance that will be cloned and used by the cipher internally. The internal instance will be erased when the Cipher.erase()
method is called.AlgorithmIdentifierException
- is thrown if the algID's Object ID isn't valid for the Cipher instance being initialized or if the params are not valid for the algID's Object ID.InvalidKeyException
- is thrown if there is a problem with the Key instance the Cipher is being initialized with.CipherException
- is thrown if there is a problem initializing the Cipher.public static Cipher getInstance(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID) throws AlgorithmIdentifierException, InvalidKeyException, CipherException
The resulting instance has been initialized with the given Key, AlgorithmIdentifer, Padding.ID and no RandomBitsSource because the Cipher will load the default RandomBitsSource if it is required.
algID
- is the AlgorithmIdentifier whose params will be used to configure the cipher.key
- is the Key instance that will be cloned and used by the cipher internally. The internal instance will be erased when the Cipher.erase()
method is called.paddingID
- is used to indicate the type of padding that the Cipher should use. Options are Padding.NONE or Padding.PKCS5. A Cipher must be re-initialized before being used with the other Padding type.AlgorithmIdentifierException
- is thrown if the algID's OID isn't valid for the Cipher instance being initialized or if the params are not valid for the algID's OID.InvalidKeyException
- is thrown if there is a problem with the Key instance the Cipher is being initialized with.CipherException
- is thrown if there is a problem initializing the Cipher.public static Cipher getInstance(PrivateKey key) throws AlgorithmIdentifierException, InvalidKeyException
The resulting instance is ready to be used.
key
- is the PrivateKey whose AlgorithimIdentifier will be retrieved and used for its Object ID to locate an appropriate Cipher instance.AlgorithmIdentifierException
- is thrown if no suitable Cipher can be found for the given AlgorithmIdentifier or if there is a problem initializing the Cipher instance with the given AlgorithmIdentifier.InvalidKeyException
- is thrown if there is a problem initializing the Cipher with the Key.public static Cipher getInstance(PublicKey key) throws AlgorithmIdentifierException, InvalidKeyException
The resulting instance is ready to be used.
key
- is the PrivateKey whose AlgorithimIdentifier will be retrieved and used for its Object ID to locate an appropriate Cipher instance.AlgorithmIdentifierException
- is thrown if no suitable Cipher can be found for the given AlgorithmIdentifier or if there is a problem initializing the Cipher instance with the given AlgorithmIdentifier.InvalidKeyException
- is thrown if there is a problem initializing the Cipher with the Key.public abstract void initialize(AlgorithmIdentifier algID, Key key) throws AlgorithmIdentifierException, InvalidKeyException, CipherException
algID
- is the AlgorithmIdentifier whose params will be used to configure the cipher.key
- is the Key instance that will be cloned and used by the cipher internally. The internal instance will be erased when Cipher.erase()
is called.AlgorithmIdentifierException
- is thrown if the algID's OID isn't valid for the Cipher instance being initialized or if the params are not valid for the algID's OID.InvalidKeyException
- is thrown if there is a problem with the Key instance the Cipher is being initialized with.CipherException
- is thrown if there is a problem initializing the Cipher.public void initialize(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID) throws AlgorithmIdentifierException, InvalidKeyException, CipherException
BlockCipher
with the given algorithm parameters, symmetric key, and padding descriptor.algID
- is the AlgorithmIdentifier whose params will be used to configure the cipher.key
- is the SymmetricKey instance that will be cloned and used by the cipher internally. The internal instance will be erased when Cipher.erase()
is called.paddingID
- is used to indicate the type of padding that the Cipher should use. Options are Padding.NONE or Padding.PKCS5. A Cipher must be re-initialized before being used with the other Padding type.AlgorithmIdentifierException
- is thrown if the algID's OID isn't valid for the Cipher instance being initialized or if the params are not valid for the algID's OID.InvalidKeyException
- is thrown if there is a problem with the Key instance the Cipher is being initialized with.CipherException
- is thrown if there's a problem initializing the Cipher with the given parameters.public Key cloneKey()
public byte[] decrypt(byte[] input) throws CipherException
input
- data to be decryptedCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for encryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the decryption process.public byte[] decrypt(byte[] bytes, boolean unpad) throws CipherException
bytes
- data to be decrypted.unpad
- true if padding is to be removed, false otherwiseCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for encryption without being re-initialized, if the data is not a multiple of the block size and no padding is specified, or if an error occurred during the decryption process.public byte[] decrypt(byte[] input, int inOff, int len) throws CipherException
input
- buffer in which data to be decrypted is storedinOff
- offset within buffer of the start of datalen
- the length of the dataCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for encryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the decryption process.public abstract byte[] decrypt(byte[] input, int inOff, int len, boolean unpad) throws CipherException
input
- Buffer in which data to be decrypted is stored.inOff
- Offset within buffer of the start of data.len
- The length of the dataunpad
- specifies whether the plaintext should have padding removed.CipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for encryption without being re-initialized, if the data is not a multiple of the block size and no padding is specified, or if an error occurred during the decryption process.public abstract void decrypt(byte[] input, int inOff, int len, byte[] output, int outOff) throws CipherException
input
- array of bytes to decryptinOff
- offset of the start of the data to decryptlen
- the length of the data to decryptoutput
- array to place the decrypted bytesoutOff
- offset of the start of the decrypted bytesCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for encryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the decryption process.public final byte[] decodeOp(byte[] input) throws CipherException
Cipher.decrypt(byte[]);
This implements the Coder
interface.decodeOp
in class Coder
input
- is the data to be decryptedCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for encryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the decryption process.public byte[] encrypt(byte[] input) throws CipherException
input
- data to be encryptedCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for decryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the encryption process.public byte[] encrypt(byte[] bytes, boolean pad) throws CipherException
bytes
- Data to be encryptedpad
- True if padding is to be used, false otherwiseCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for decryption without being re-initialized, if the data is not a multiple of the block size and no padding is specified, or if an error occurred during the encryption process.public byte[] encrypt(byte[] input, int inOff, int len) throws CipherException
input
- Buffer in which data to be encrypted is stored.inOff
- Offset within buffer of the start of the data.len
- The length of the data.CipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for decryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the encryption process.public abstract byte[] encrypt(byte[] input, int inOff, int len, boolean pad) throws CipherException
input
- buffer in which data to be encrypted is stored.inOff
- offset within buffer of the start of the data.len
- the length of the data.pad
- true if padding is to be used, false otherwise.CipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for decryption without being re-initialized, if the data is not a multiple of the block size and no padding is specified, or if an error occurred during the encryption process.public abstract void encrypt(byte[] input, int inOff, int len, byte[] output, int outOff) throws CipherException
input
- array of bytes to encryptinOff
- offset of the start of data to encryptlen
- the length of the data to encryptoutput
- array to place the encrypted bytesoutOff
- offset of the start of the encrypted bytesCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for decryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the encryption process.public final byte[] encodeOp(byte[] input) throws CipherException
Cipher.encrypt(byte[]);
. This implements the Coder interface.encodeOp
in class Coder
input
- is the data to be encryptedCipherException
- is thrown if the Cipher was not initialized, if the Cipher was used for decryption without being re-initialized, if the data is not a multiple of the block size, or if an error occurred during the encryption process.public void erase()
public abstract AlgorithmIdentifier getAlgID()
Altering this AlgorithmIdentifier will have no effect on the state of the Cipher.
public int getMode()
public Padding.ID getPaddingID()
Padding.ID
public abstract int getBlockSize()
getBlockSize
in class Coder
public byte[] getIV()
Note: Only BlockCiphers use initialization vectors
protected final void releaseOp()
protected final void assertDecryption() throws CipherException
CipherException
- is thrown if the Cipher is already locked into Encryption mode.protected final void assertEncryption() throws CipherException
CipherException
- is thrown if the Cipher is already locked into Decryption mode.public abstract int blockSize()
getBlockSize()
instead.blockSize
in class Coder
public abstract void decryptOp(byte[] in, int inOff, byte[] out, int outOff) throws CipherException
Implementors must ensure that this method works correctly even if the 'in' and 'out' buffers coincide.
in
- buffer in which data to be decrypted is stored.inOff
- offset within input buffer of the start of data.out
- buffer to place the decrypted bytes inoutOff
- offset within output buffer where the encrypted bytes will be stored.CipherException
- is thrown if the Cipher is not initialized, length of data is not equal to the block size, etc.public byte[] decryptOp(byte[] bytes) throws CipherException
bytes
- is the data to be decryptedCipherException
- is thrown if the cipher is not initialized, length of data is not equal to the block size, etc.public abstract void encryptOp(byte[] in, int inOff, byte[] out, int outOff) throws CipherException
Implementors must ensure that this method works correctly even if the 'in' and 'out' buffers coincide.
in
- buffer in which data to be encrypted is storedinOff
- offset within input buffer of the start of dataout
- buffer to place the encrypted bytes inoutOff
- offset within output buffer where the encrypted bytes will be storedCipherException
- is thrown if the Cipher is not initialized, length of data is not equal to the block size, etc.public byte[] encryptOp(byte[] bytes) throws CipherException
bytes
- is the data to be encrypted.CipherException
- if cipher not initialized, length of data is not equal to the block size, etc.public byte[] pad(byte[] bytes) throws CipherException
CipherException
- If no padding has been specified, and length of the array is not a multiple of the block size.public byte[] unpad(byte[] bytes) throws CipherException
CipherException
- If no padding has been specified, and length of the array is not a multiple of the block size.public abstract void setAlgID(AlgorithmIdentifier algID) throws AlgorithmIdentifierException
AlgorithmIdentifierException
public SymmetricKey getKey()
cloneKey()
instead.public void setKey(SymmetricKey key) throws InvalidKeyException
InvalidKeyException
- is thrown if the the key is not valid for the Cipher instancepublic Key getEncryptionKey()
cloneKey()
instead.public void setEncryptionKey(Key key) throws InvalidKeyException
InvalidKeyException
- is thrown if the the key is not valid for the Cipher instancepublic Key getDecryptionKey()
cloneKey()
instead.public void setDecryptionKey(Key key) throws InvalidKeyException
InvalidKeyException
- is thrown if the the key is not valid for the Cipher instancepublic int getPadding()
getPaddingID()
instead.Padding.NONE
.public void setPadding(int padding)
Padding.NONE
.public void setMode(int mode)
public void setRandomBitsSource(RandomBitsSource rbs)
RandomBitsSource
for the Cipher instance.public void setIV(byte[] iv) throws CipherException
iv
- the initialization vectorCipherException
|
Oracle Security Developer Tools Crypto Java API Reference 10g (10.1.4.0.1) B28171-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |