|
Oracle Fusion Middleware Crypto Java API Reference for Oracle Security Developer Tools 11g Release 1 (11.1.1) E10668-03 |
||||||||
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
public abstract class 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. |
static int |
ECB Electronic Code Book (ECB) mode (default). |
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. |
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. |
protected void |
assertKeyUnwrap() Used by subclasses to lock the cipher into Key-Unwrap mode. |
protected void |
assertKeyWrap() Used by subclasses to lock the cipher into Key-Wrap mode. |
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[] |
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. |
void |
erase() Erases any sensitive information (such as buffers and subkey tables) stored in this cipher object. |
void |
finalize() Finalizes this Cipher object by calling the erase() method and erasing all sensitive data. |
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. |
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, Key key, RandomBitsSource rbs) 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(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID, RandomBitsSource rbs) 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. |
int |
getMode() Returns the block mode used by this cipher. |
Padding.ID |
getPaddingID() Gets the ID of the Padding used by the Cipher. |
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. |
abstract void |
initialize(AlgorithmIdentifier algID, Key key, RandomBitsSource rbs) 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. |
void |
initialize(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID, RandomBitsSource rbs) This method may be used to initialize a BlockCipher with the given algorithm parameters, symmetric key, and padding descriptor. |
protected void |
releaseOp() Used by subclasses to release the Cipher instance for use by another operation. |
abstract PrivateKey |
unwrapPrivateKey(byte[] encKey) Unwraps a private key using this cipher. |
abstract SymmetricKey |
unwrapSymmetricKey(byte[] encKey, AlgorithmIdentifier algID) Unwraps a symmetric key using this cipher. |
abstract byte[] |
wrapKey(PrivateKey key) Wraps a private key using this cipher. |
abstract byte[] |
wrapKey(SymmetricKey key) Wraps a symmetric key using this cipher. |
Methods inherited from class oracle.security.crypto.core.Coder |
---|
algName, decode, decode, encode, encode |
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected int mode
protected Key key
protected RandomBitsSource rbs
public static final int ECB
public static final int CBC
Constructor Detail |
---|
protected Cipher()
Method Detail |
---|
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
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will used by the cipher internally.AlgorithmIdentifierException
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- If there is a problem initializing the Cipher.public static Cipher getInstance(AlgorithmIdentifier algID, Key key, RandomBitsSource rbs) 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
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will used by the cipher internally.rbs
- The RandomBitsSourfce to use in this cipher.AlgorithmIdentifierException
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- 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
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will used by the cipher internally.paddingID
- 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
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- If there is a problem initializing the Cipher.public static Cipher getInstance(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID, RandomBitsSource rbs) 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
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will used by the cipher internally.paddingID
- 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.rbs
- The RandomBitsSourfce to use in this cipher.AlgorithmIdentifierException
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- 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
- The PrivateKey whose AlgorithmIdentifier will be retrieved and used for its Object ID to locate an appropriate Cipher instance.AlgorithmIdentifierException
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.public static Cipher getInstance(PublicKey key) throws AlgorithmIdentifierException, InvalidKeyException
The resulting instance is ready to be used.
key
- The PublicKey whose AlgorithmIdentifier will be retrieved and used for its Object ID to locate an appropriate Cipher instance.AlgorithmIdentifierException
- 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
- If there is a problem initializing the Cipher with the Key.public void initialize(AlgorithmIdentifier algID, Key key) throws AlgorithmIdentifierException, InvalidKeyException, CipherException
algID
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will be used by the cipher internally.AlgorithmIdentifierException
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- If there is a problem initializing the Cipher.public abstract void initialize(AlgorithmIdentifier algID, Key key, RandomBitsSource rbs) throws AlgorithmIdentifierException, InvalidKeyException, CipherException
algID
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will be used by the cipher internally.rbs
- The RandomBitsSourfce to use in this cipher.AlgorithmIdentifierException
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- 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
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will be used by the cipher internally.paddingID
- 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
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- If there is a problem initializing the Cipher.public void initialize(AlgorithmIdentifier algID, SymmetricKey key, Padding.ID paddingID, RandomBitsSource rbs) throws AlgorithmIdentifierException, InvalidKeyException, CipherException
BlockCipher
with the given algorithm parameters, symmetric key, and padding descriptor.algID
- The AlgorithmIdentifier whose params will be used to configure the cipher.key
- The Key instance that will be used by the cipher internally.paddingID
- 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.rbs
- The RandomBitsSourfce to use in this cipher.AlgorithmIdentifierException
- 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
- If there is a problem with the Key instance the Cipher is being initialized with.CipherException
- If there is a problem initializing the Cipher.public Key cloneKey()
public byte[] decrypt(byte[] input) throws CipherException
input
- The data to be decrypted.CipherException
- 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
- The data to be decrypted.unpad
- true
if padding is to be removed, false
otherwise.CipherException
- 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[] input, int inOff, int len) throws CipherException
input
- The buffer in which data to be decrypted is stored.inOff
- The offset within buffer of the start of data.len
- The length of the data.CipherException
- 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
- The buffer in which data to be decrypted is stored.inOff
- The offset within buffer of the start of data.len
- The length of the data.unpad
- Specifies whether the plaintext should have padding removed.CipherException
- 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
- The buffer in which data to be decrypted is stored.inOff
- The offset within buffer of the start of data.len
- The length of the data.output
- The array to place the decrypted bytes.outOff
- The offset of the start of the decrypted bytes.CipherException
- 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
- The data to be decrypted.CipherException
- 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
- The data to be encrypted.CipherException
- 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
- The data to be encrypted.pad
- true
if padding is to be used, false
otherwise.CipherException
- 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
- The buffer in which data to be encrypted is stored.inOff
- The offset within buffer of the start of the data.len
- The length of the data.CipherException
- 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
- The buffer in which data to be encrypted is stored.inOff
- The 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
- 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
- The array of bytes to encrypt.inOff
- The offset of the start of data to encrypt.len
- The length of the data to encrypt.output
- The array to place the encrypted bytes.outOff
- The offset of the start of the encrypted bytes.CipherException
- 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
- The data to be encrypted.CipherException
- 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[] wrapKey(PrivateKey key) throws CipherException
key
- The private key to wrap.CipherException
- If the Cipher was not initialized, if the Cipher was used for wrapping without being re-initialized or if an error occurred during the wrapping process.public abstract byte[] wrapKey(SymmetricKey key) throws CipherException
key
- The symmetric key to wrap.CipherException
- If the Cipher was not initialized, if the Cipher was used for wrapping without being re-initialized or if an error occurred during the wrapping process.public abstract PrivateKey unwrapPrivateKey(byte[] encKey) throws CipherException
encKey
- The encrypted key.CipherException
- If the Cipher was not initialized, if the Cipher was used for unwrapping without being re-initialized or if an error occurred during the decryption process.public abstract SymmetricKey unwrapSymmetricKey(byte[] encKey, AlgorithmIdentifier algID) throws CipherException
encKey
- The encrypted key.algID
- The algorithm identifier of the wrapped symmetric key.CipherException
- If the Cipher was not initialized, if the Cipher was used for unwrapping without being re-initialized or if an error occurred during the encryption process.public void erase()
public void finalize()
finalize
in class java.lang.Object
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 another mode.protected final void assertEncryption() throws CipherException
CipherException
- is thrown if the Cipher is already locked into another mode.protected final void assertKeyWrap() throws CipherException
CipherException
- If the Cipher is already locked into another mode.protected final void assertKeyUnwrap() throws CipherException
CipherException
- If the Cipher is already locked into another mode.
|
Oracle Fusion Middleware Crypto Java API Reference for Oracle Security Developer Tools 11g Release 1 (11.1.1) E10668-03 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |