- java.lang.Object
-
- javax.crypto.CipherSpi
-
- com.ibm.crypto.hdwrCCA.provider.AESCipher
-
public final class AESCipher extends javax.crypto.CipherSpi
This class implements the AES algorithm in its various modes (ECB
,CBC
,CFB
,OFB
,GCM
) and padding schemes (PKCS5Padding
,NoPadding
). AES hardware supports these modes. If AES hardware is not available, then if ICSF and DESede hardware are available, the ICSF software implementation will be used.If the following are true:
- The cipher mode is GCM and
- A GCMParameterSpec is specified to the
engineInit(int, Key, AlgorithmParameterSpec, SecureRandom)
method of this cipher
key_parms_length
. Note that, although the tag length specified in the GCMParameterSpec is in bits, the valid tag lengths listed in the ICSF Application Programmer's Guide are in bytes. (For example, a GCMParameterSpec TLen value of 112 corresponds to an ICSF tag length of 14.)This documentation describes a Service Provider Interface. It is provided for implementation insight only. This class is not intended to be called directly by application developers. Please consult the 'Java Cryptography Architecture Standard' for details on how to use this interface through a public standard class.
- Note:
- Certain operations may require specific hardware or software, or specific key types. See the rest of this document and the z/OS Unique Considerations Hardware Crypto Reference Guide for more details. Unsupported operations and/or combinations may result in a RuntimeException Hardware Error.
-
-
Field Summary
Fields Modifier and Type Field Description protected static int
CBC_MODE
CBC mode encryption.protected static int
CFB_MODE
CFB mode encryption.protected int
cipherMode
The cipher mode.static int
DEFAULT_TAG_LENGTH
Default value for tLen, used for GCM mode if no GCMParameterSpec is passed to init().protected static int
ECB_MODE
ECB mode encryption.protected static int
GCM_MODE
GCM mode encryption.protected static int
OFB_MODE
OFB mode encryption.protected com.ibm.crypto.hdwrCCA.provider.AESCrypt
rawAlg
The (raw) algorithm.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected byte[]
engineDoFinal(byte[] input, int inputOffset, int inputLen)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.protected int
engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.protected int
engineGetBlockSize()
Returns the block size (in bytes).protected byte[]
engineGetIV()
Returns the initialization vector (IV) in a new buffer.protected int
engineGetKeySize(java.security.Key key)
Returns the key size of the given key object.protected int
engineGetOutputSize(int inputLen)
Returns the length in bytes that an output buffer would need to be in order to hold the result of the nextupdate
ordoFinal
operation, given the input lengthinputLen
(in bytes).protected java.security.AlgorithmParameters
engineGetParameters()
Returns the parameters used with this cipher.protected void
engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random)
Initializes this cipher with an opmode, a key, a set of algorithm parameters, and a source of randomness.protected void
engineInit(int opmode, java.security.Key key, java.security.SecureRandom random)
Initializes this cipher with an opmode, a key and a source of randomness.protected void
engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random)
Initializes this cipher with an opmode, a key, a set of algorithm parameters, and a source of randomness.protected void
engineSetMode(java.lang.String mode)
Sets the mode of this cipher.protected void
engineSetPadding(java.lang.String paddingScheme)
Sets the padding mechanism of this cipher.protected java.security.Key
engineUnwrap(byte[] wrappedKey, java.lang.String wrappedKeyAlgorithm, int wrappedKeyType)
Unwrap a previously wrapped key.protected byte[]
engineUpdate(byte[] input, int inputOffset, int inputLen)
Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.protected int
engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.protected void
engineUpdateAAD(byte[] src)
Begins or continues a multi-part update of the Additional Authentication Data (AAD) for GCM mode only.protected void
engineUpdateAAD(byte[] src, int offset, int len)
Begins or continues a multi-part update of the Additional Authentication Data (AAD) for GCM mode only.protected byte[]
engineWrap(java.security.Key key)
Wrap a key.protected void
setRawAlg()
Sets the raw algorithm to AES.
-
-
-
Field Detail
-
cipherMode
protected int cipherMode
The cipher mode. One of ECB, CBC, GCM, CFB, CFBnn or OFB.
-
ECB_MODE
protected static final int ECB_MODE
ECB mode encryption. ECB mode encryption can be performed with CLEAR keys (also known as RAW keys), with CKDS keys for clear and encrypted keys (also known as CKDSLabel keys), with SECURE_INTERNAL_TOKEN keys (also known as ICSFToken keys).- See Also:
- Constant Field Values
-
CBC_MODE
protected static final int CBC_MODE
CBC mode encryption. CBC mode encryption can be performed with CLEAR keys (also known as RAW keys), with CKDS keys for clear and encrypted keys (also known as CKDSLabel keys), with SECURE_INTERNAL_TOKEN keys (also known as ICSFToken keys).- See Also:
- Constant Field Values
-
CFB_MODE
protected static final int CFB_MODE
CFB mode encryption. CFB mode encryption can be performed with CLEAR keys (also known as RAW keys) and with CKDS keys for clear and encrypted keys (also known as CKDSLabel keys).- See Also:
- Constant Field Values
-
OFB_MODE
protected static final int OFB_MODE
OFB mode encryption. OFB mode encryption can be performed with CLEAR keys (also known as RAW keys) and with CKDS keys for clear and encrypted keys (also known as CKDSLabel keys).- See Also:
- Constant Field Values
-
GCM_MODE
protected static final int GCM_MODE
GCM mode encryption. GCM mode encryption can be performed with CLEAR keys (also known as RAW keys) and with CKDS keys for clear and encrypted keys (also known as CKDSLabel keys).- See Also:
- Constant Field Values
-
DEFAULT_TAG_LENGTH
public static final int DEFAULT_TAG_LENGTH
Default value for tLen, used for GCM mode if no GCMParameterSpec is passed to init().- See Also:
- Constant Field Values
-
rawAlg
protected com.ibm.crypto.hdwrCCA.provider.AESCrypt rawAlg
The (raw) algorithm. This is the implementation of the raw AES algorithm, which can be plugged (viasetEmbeddedCipher
) into one of the cipher mode classesCipherBlockChaining
,CipherFeedback
,ElectronicCodeBook
, orOutputFeedback
.
-
-
Constructor Detail
-
AESCipher
public AESCipher() throws java.security.NoSuchAlgorithmException, javax.crypto.NoSuchPaddingException
Creates an instance of AES cipher with default CBC mode and PKCS5Padding.- NOTE:
- The mode chosen may not support all key types. See the Field Summary mode documentation and the z/OS Unique Considerations Hardware Crypto Reference Guide for more information.
- Throws:
java.lang.SecurityException
- if this constructor fails to authenticate the JCE framework.java.security.NoSuchAlgorithmException
javax.crypto.NoSuchPaddingException
-
AESCipher
public AESCipher(java.lang.String mode, java.lang.String paddingScheme) throws java.security.NoSuchAlgorithmException, javax.crypto.NoSuchPaddingException
Creates an instance of AES cipher with the requested mode and padding.- NOTE:
- The mode chosen may not support all key types. See the Field Summary mode documentation and the z/OS Unique Considerations Hardware Crypto Reference Guide for more information.
- Parameters:
mode
- the cipher modepaddingScheme
- the padding mechanism- Throws:
java.security.NoSuchAlgorithmException
- if the required cipher mode is unavailablejavax.crypto.NoSuchPaddingException
- if the required padding mechanism is unavailablejava.lang.SecurityException
- if this constructor fails to authenticate the JCE framework.
-
-
Method Detail
-
setRawAlg
protected void setRawAlg()
Sets the raw algorithm to AES. This method is not a supported customer interface.
-
engineSetMode
protected void engineSetMode(java.lang.String mode) throws java.security.NoSuchAlgorithmException
Sets the mode of this cipher. This method is not a supported customer interface.- Specified by:
engineSetMode
in classjavax.crypto.CipherSpi
- Parameters:
mode
- the cipher mode- Throws:
java.security.NoSuchAlgorithmException
- if the requested cipher mode does not exist
-
engineSetPadding
protected void engineSetPadding(java.lang.String paddingScheme) throws javax.crypto.NoSuchPaddingException
Sets the padding mechanism of this cipher. This method is not a supported customer interface.- Specified by:
engineSetPadding
in classjavax.crypto.CipherSpi
- Parameters:
paddingScheme
- the padding mechanism- Throws:
javax.crypto.NoSuchPaddingException
- if the requested padding mechanism does not exist
-
engineGetBlockSize
protected int engineGetBlockSize()
Returns the block size (in bytes).- Specified by:
engineGetBlockSize
in classjavax.crypto.CipherSpi
- Returns:
- the block size (in bytes).
-
engineGetOutputSize
protected int engineGetOutputSize(int inputLen)
Returns the length in bytes that an output buffer would need to be in order to hold the result of the nextupdate
ordoFinal
operation, given the input lengthinputLen
(in bytes).This call takes into account any unprocessed (buffered) data from a previous
update
call, and padding.The actual output length of the next
update
ordoFinal
call may be smaller than the length returned by this method.- Specified by:
engineGetOutputSize
in classjavax.crypto.CipherSpi
- Parameters:
inputLen
- the input length (in bytes)- Returns:
- the required output buffer size (in bytes).
- Throws:
java.lang.IllegalStateException
- if this method is called in GCM mode and no GCMParameterSpec has yet been passed toengineInit(int, Key, AlgorithmParameterSpec, SecureRandom)
.
-
engineGetIV
protected byte[] engineGetIV()
Returns the initialization vector (IV) in a new buffer.This is useful in the case where a random IV has been created (see
engineInit(int, Key, SecureRandom)
), or in the context of password-based encryption or decryption, where the IV is derived from a user-provided password.- Specified by:
engineGetIV
in classjavax.crypto.CipherSpi
- Returns:
- the initialization vector in a new buffer, or null if the underlying algorithm does not use an IV, or if the IV has not yet been set.
-
engineInit
protected void engineInit(int opmode, java.security.Key key, java.security.SecureRandom random) throws java.security.InvalidKeyException
Initializes this cipher with an opmode, a key and a source of randomness.The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of
opmode
.If this cipher requires an initialization vector (IV), it will get it from
random
. This behaviour should only be used in encryption or key wrapping mode, however. When initializing a cipher that requires an IV for decryption or key unwrapping, the IV (same IV that was used for encryption or key wrapping) must be provided explicitly as a parameter, in order to get the correct result.This method also cleans existing buffer and other related state information.
- Specified by:
engineInit
in classjavax.crypto.CipherSpi
- Parameters:
opmode
- the operation mode of this cipher (this is one of the following:ENCRYPT_MODE
,DECRYPT_MODE
,WRAP_MODE
orUNWRAP_MODE
)key
- the secret keyrandom
- the source of randomness- Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for initializing this cipher.
-
engineInit
protected void engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException
Initializes this cipher with an opmode, a key, a set of algorithm parameters, and a source of randomness.The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of
opmode
.If this cipher (including its underlying feedback or padding scheme) requires any random bytes, it will get them from
random
.- Specified by:
engineInit
in classjavax.crypto.CipherSpi
- Parameters:
opmode
- the operation mode of this cipher (this is one of the following:ENCRYPT_MODE
,DECRYPT_MODE
,WRAP_MODE
orUNWRAP_MODE
)key
- the encryption key.params
- the algorithm parameter spec. See the class description for information regarding this parameter when using GCM mode.random
- the source of randomness- Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for initializing this cipherjava.security.InvalidAlgorithmParameterException
- if the given algorithm parameters are inappropriate for this cipher
-
engineInit
protected void engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException
Initializes this cipher with an opmode, a key, a set of algorithm parameters, and a source of randomness.The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of
opmode
.If this cipher (including its underlying feedback or padding scheme) requires any random bytes, it will get them from
random
.- Specified by:
engineInit
in classjavax.crypto.CipherSpi
- Parameters:
opmode
- the operation mode of this cipher (this is one of the following:ENCRYPT_MODE
,DECRYPT_MODE
,WRAP_MODE
orUNWRAP_MODE
)key
- the encryption keyparams
- the algorithm parametersrandom
- the source of randomness- Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for initializing this cipherjava.security.InvalidAlgorithmParameterException
- if the given algorithm parameters are inappropriate for this cipher
-
engineUpdateAAD
protected void engineUpdateAAD(byte[] src) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.lang.UnsupportedOperationException
Begins or continues a multi-part update of the Additional Authentication Data (AAD) for GCM mode only. Calls to this method provide AAD to the cipher when operating in GCM mode. If this cipher is operating in GCM mode, all AAD must be supplied before beginning operations on the text/cipherText.- Parameters:
src
- the buffer containing the AAD- Throws:
java.lang.IllegalArgumentException
- if thesrc
byte array is emptyjava.lang.IllegalStateException
- if this cipher is in a wrong state (e.g., has not been initialized) or if this method is called when not in GCM mode.java.lang.UnsupportedOperationException
- is not thrown by this method but is required by the specification.
-
engineUpdateAAD
protected void engineUpdateAAD(byte[] src, int offset, int len) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.lang.UnsupportedOperationException
Begins or continues a multi-part update of the Additional Authentication Data (AAD) for GCM mode only. Calls to this method provide AAD to the cipher when operating in GCM mode. If this cipher is operating in GCM mode, all AAD must be supplied before beginning operations on the text/cipherText.- Overrides:
engineUpdateAAD
in classjavax.crypto.CipherSpi
- Parameters:
src
- the buffer containing the AADoffset
- the offset insrc
where the AAD input startslen
- the number of AAD bytes- Throws:
java.lang.IllegalArgumentException
- if thesrc
byte array is null or emptyjava.lang.IllegalStateException
- if this cipher is in a wrong state (e.g., has not been initialized) or if this method is called when not in GCM mode.java.lang.UnsupportedOperationException
- is not thrown by this method but is required by the specification.
-
engineUpdate
protected byte[] engineUpdate(byte[] input, int inputOffset, int inputLen)
Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.The first
inputLen
bytes in theinput
buffer, starting atinputOffset
, are processed, and the result is stored in a new buffer.This method is not supported in GCM mode.
- Specified by:
engineUpdate
in classjavax.crypto.CipherSpi
- Parameters:
input
- the input bufferinputOffset
- the offset ininput
where the input startsinputLen
- the input length- Returns:
- the new buffer with the result.
- Throws:
java.lang.IllegalStateException
-- if this cipher is in a wrong state (e.g., has not been initialized).
- if this method is called in GCM mode.
-
engineUpdate
protected int engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) throws javax.crypto.ShortBufferException
Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.The first
inputLen
bytes in theinput
buffer, starting atinputOffset
, are processed, and the result is stored in theoutput
buffer, starting atoutputOffset
.This method is not supported in GCM mode.
- Specified by:
engineUpdate
in classjavax.crypto.CipherSpi
- Parameters:
input
- the input bufferinputOffset
- the offset ininput
where the input startsinputLen
- the input lengthoutput
- the buffer for the resultoutputOffset
- the offset inoutput
where the result is stored- Returns:
- the number of bytes stored in
output
. - Throws:
javax.crypto.ShortBufferException
- if the given output buffer is too small to hold the resultjava.lang.IllegalStateException
- if this method is called in GCM mode.
-
engineDoFinal
protected byte[] engineDoFinal(byte[] input, int inputOffset, int inputLen) throws javax.crypto.IllegalBlockSizeException, javax.crypto.BadPaddingException
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. The data is encrypted or decrypted, depending on how this cipher was initialized.The first
inputLen
bytes in theinput
buffer, starting atinputOffset
, and any input bytes that may have been buffered during a previousupdate
operation, are processed, with padding (if requested) being applied. The result is stored in a new buffer.The cipher is reset to its initial state (uninitialized) after this call.
- Specified by:
engineDoFinal
in classjavax.crypto.CipherSpi
- Parameters:
input
- the input bufferinputOffset
- the offset ininput
where the input startsinputLen
- the input length- Returns:
- the new buffer with the result.
- Throws:
javax.crypto.IllegalBlockSizeException
- if this cipher is a block cipher, no padding has been requested (only in encryption mode), and the total input length of the data processed by this cipher is not a multiple of block size.javax.crypto.BadPaddingException
- if this cipher is in decryption mode, and (un)padding has been requested, but the decrypted data is not bounded by the appropriate padding bytes.java.lang.IllegalArgumentException
- if this method is called for decryption in GCM mode and the input buffer is not large enough to contain the authentication tag.
-
engineDoFinal
protected int engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) throws javax.crypto.IllegalBlockSizeException, javax.crypto.ShortBufferException, javax.crypto.BadPaddingException
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. The data is encrypted or decrypted, depending on how this cipher was initialized.The first
inputLen
bytes in theinput
buffer, starting atinputOffset
, and any input bytes that may have been buffered during a previousupdate
operation, are processed, with padding (if requested) being applied. The result is stored in theoutput
buffer, starting atoutputOffset
.The cipher is reset to its initial state (uninitialized) after this call.
- Specified by:
engineDoFinal
in classjavax.crypto.CipherSpi
- Parameters:
input
- the input bufferinputOffset
- the offset ininput
where the input startsinputLen
- the input lengthoutput
- the buffer for the resultoutputOffset
- the offset inoutput
where the result is stored- Returns:
- the number of bytes stored in
output
. - Throws:
javax.crypto.IllegalBlockSizeException
- if this cipher is a block cipher, no padding has been requested (only in encryption mode), and the total input length of the data processed by this cipher is not a multiple of block size.javax.crypto.ShortBufferException
- if the given output buffer is too small to hold the result.javax.crypto.BadPaddingException
- if this cipher is in decryption mode, and (un)padding has been requested, but the decrypted data is not bounded by the appropriate padding bytes.javax.crypto.AEADBadTagException
- if this cipher is in GCM decryption mode, and the AuthenticationTag was not verified correct.JCECCARuntimeException
- if the native API reports an error. If using GCM mode and the message indicates that CSNBSYE or CSNBSYD returned (8,11000), this can be caused by an invalid authentication tag length specified in the GCMParameterSpec passed toengineInit(int, Key, AlgorithmParameterSpec, SecureRandom)
. For more information, see the class description.java.lang.IllegalArgumentException
-- if the cipher is in GCM mode and if both the AdditionalAuthenticationData (AAD) and the input text have length of zero.
- if the cipher is in GCM mode and if decrypting, and the input text length is less than that AuthenticationTagLength (Tlen).
- if the cipher is in GCM mode and if length specified for the AuthenticationTagLength (Tlen) is not supported by ICSF.
-
engineGetParameters
protected java.security.AlgorithmParameters engineGetParameters()
Returns the parameters used with this cipher.The returned parameters may be the same that were used to initialize this cipher, or may contain the default set of parameters or a set of randomly generated parameters used by the underlying cipher implementation (provided that the underlying cipher implementation uses a default set of parameters or creates new parameters if it needs parameters but was not initialized with any).
- Specified by:
engineGetParameters
in classjavax.crypto.CipherSpi
- Returns:
- the parameters used with this cipher, null if this cipher does not use any parameters, or null if this cipher has not been initialized.
-
engineGetKeySize
protected int engineGetKeySize(java.security.Key key)
Returns the key size of the given key object.This method is called by the JCE framework to ensure that the size of the key to be used does not exceed the maximum allowable key size specified in the Java restricted policy files.
Since cryptographic operations using AES ciphers are always done at the cryptographic hardware level, and the hardware itself enforces the US export restrictions relating to cryptographic keys, we should always return a key size that will pass the restricted policy files check done by the JCE framework.
- Overrides:
engineGetKeySize
in classjavax.crypto.CipherSpi
- Parameters:
key
- the key object.- Returns:
- a key size that will pass the restricted policy files check done by the JCE framework.
-
engineWrap
protected byte[] engineWrap(java.security.Key key) throws javax.crypto.IllegalBlockSizeException, java.security.InvalidKeyException
Wrap a key.This method is not supported in GCM mode.
- Overrides:
engineWrap
in classjavax.crypto.CipherSpi
- Parameters:
key
- the key to be wrapped. This key must be aRAW
Cipher.SECRET_KEY
. This cipher does not support wrapping secret keys of typeICSFToken
or typeCKDSLabel
, and does not support wrappingCipher.PRIVATE_KEY
orCipher.PUBLIC_KEY
.- Returns:
- the wrapped key.
- Throws:
javax.crypto.IllegalBlockSizeException
- if this cipher is a block cipher, no padding has been requested, and the length of the encoding of the key to be wrapped is not a multiple of the block size.java.security.InvalidKeyException
- if any of the following is true:- it is impossible or unsafe to wrap the key with this cipher (for example, a hardware protected key is being passed to a software only cipher)
- the key is a
Cipher.PRIVATE_KEY
- the key is a
Cipher.PUBLIC_KEY
- the key is a
Cipher.SECRET_KEY
but is not typeRAW
key
java.lang.IllegalStateException
- if this method is called in GCM mode.
-
engineUnwrap
protected java.security.Key engineUnwrap(byte[] wrappedKey, java.lang.String wrappedKeyAlgorithm, int wrappedKeyType) throws java.security.InvalidKeyException, java.security.NoSuchAlgorithmException
Unwrap a previously wrapped key.This method is not supported in GCM mode.
- Overrides:
engineUnwrap
in classjavax.crypto.CipherSpi
- Parameters:
wrappedKey
- the key to be unwrapped.wrappedKeyAlgorithm
- the algorithm the wrapped key is for.wrappedKeyType
- the type of the wrapped key. This must beCipher.SECRET_KEY
. This cipher does not support unwrapping a key of typeCipher.PRIVATE_KEY
orCipher.PUBLIC_KEY
.- Returns:
- the unwrapped key.
- Throws:
java.security.InvalidKeyException
- if any of the following is true:wrappedKey
does not represent a wrapped key- the algorithm associated with the wrapped key is different from
wrappedKeyAlgorithm
- its key type is different from
wrappedKeyType
- the wrappedKeyType parameter is not
Cipher.SECRET_KEY
java.security.NoSuchAlgorithmException
- if no installed providers can create keys for thewrappedKeyAlgorithm
.java.lang.IllegalStateException
- if this method is called in GCM mode.
-
-