iaik.security.cipher

Class AESKeyWrapWithPadding

java.lang.Object

javax.crypto.CipherSpi

iaik.security.cipher.AESKeyWrap

iaik.security.cipher.AESKeyWrapWithPadding

public class AESKeyWrapWithPadding
extends AESKeyWrap

This class implements the AES key wrap with padding algorithm according to RFC 5649.

The AES key wrap algorithm specified by RFC 3394 maybe used for wrapping AES content encryption keys with AES key encryption keys. However, RFC 3394 requires that the size of the to-be-wrapped key is a multiple of 64 bits. As an extension to RFC 3394 a padding mechanism for the AES key wrap algorithm is specified in RFC 5649 allowing to also wrap keys with a size that is not a multiple of 64 bits.

When calling an engineInit method any parameters supplied are ignored; this AES key wrap cipher implementation itself takes care for using the right initialization vector for the right wrap/unwrap step. When calling method getIV or getParameters this class always returns null since a AES key wrap cipher does not include parameters in its algorithm id.

When creating a new AES key wrap Cipher object you only may provide the name of the key wrap cipher ("AESWrapWithPadding"). Any cipher mode (always uses ECB) or padding (uses RFC 5649 padding) specification is ignored.

For example, wrapping some key using a AES 128 bit key encryption key typically may be done as follows:

 // the key to be wrapped:
 String keyAlg = ...;
 Key keyToBeWrapped = ...;
 // the key encryption key to be used:
 SecretKey kek = ...;
 // get a AES key wrap cipher:
 Cipher c = Cipher.getInstance("AESWrapWithPadding", "IAIK");
 // init with the key encryption key
 c.init(Cipher.WRAP_MODE, kek);
 // wrap the key:
 byte[] wrappedKey = c.wrap(keyToBeWrapped);
 

For unwrapping the key init the Cipher in unwrap mode:

 Cipher c = Cipher.getInstance("AESWrapWithPadding", "IAIK");
 // init with the key encryption key
 c.init(Cipher.UNWRAP_MODE, kek);
 // unwrap the wrapped key:
 Key unwrappedKey = c.unwrap(wrappedKey, keyAlg, Cipher.SECRET_KEY);
 

For using a 192 or 256 bit key encryption key simply create and init the cipher with a key encryption key of the desired bit length.

The maximum size of keys that can be wrapped using the algorithm specified by RFC 5649 is 2³² octets. This is more than a byte array can hold, thus this implementation does not check for upper key size limits. However, an application using this algorithm may impose upper key size bounds that are much less than 2³² octets (see RFC 5649).

Version:

File Revision 12

See Also:

Cipher, SecretKey

Field Summary

Fields

Modifier and Type	Field and Description
static byte[]	NIST_KEY_WRAP_IV The initial vector defined for the NIST symmetric key wrap algorithm.

Constructor Summary

Constructors

Constructor and Description
AESKeyWrapWithPadding() Creates a new instance of this AESKeyWrapWithPadding cipher.

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	engineDoFinal(byte[] input, int inputOffset, int inputLen) Performs the final step of a en/decryption (wrapping/unwrappin) operation by processing the given input data and any remaining buffered data.
int	engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Performs the final step of a en/decryption (wrapping/unwrappin) operation by processing the given input data and any remaining buffered data.
int	engineGetBlockSize() Returns the block size corresponding to this cipher.
byte[]	engineGetIV() Returns a byte array containing the initialization vector (IV).
protected int	engineGetKeySize(java.security.Key key)
int	engineGetOutputSize(int inLen) Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.
java.security.AlgorithmParameters	engineGetParameters() Gets the algorithm parameters used/generated by this Cipher engine.
void	engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this cipher object with proper key and algorithm parameter values, and some random seed.
void	engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random) Initializes this cipher object with proper key and algorithm parameter values, and some random seed.
void	engineInit(int opmode, java.security.Key key, java.security.SecureRandom random) Initializes this cipher object with a proper key and some random seed.
void	engineSetMode(java.lang.String mode) Sets the mode of this cipher.
protected java.security.Key	engineUnwrap(byte[] wrappedKey, java.lang.String wrappedKeyAlgorithm, int wrappedKeyType)
byte[]	engineUpdate(byte[] input, int inputOffset, int inputLen) Updates this Cipher with the given data bytes.
int	engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Updates this Cipher with the given data bytes.
protected void	engineUpdateAAD(byte[] src, int offset, int len)
protected byte[]	engineWrap(java.security.Key key)
int	getModeBlockSize() Returns the block size corresponding to the actual cipher mode.
java.lang.String	toString() Returns a string representation of this Cipher.

Methods inherited from class iaik.security.cipher.AESKeyWrap

engineSetPadding

Methods inherited from class javax.crypto.CipherSpi

engineDoFinal, engineUpdate, engineUpdateAAD

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NIST_KEY_WRAP_IV

public static final byte[] NIST_KEY_WRAP_IV

The initial vector defined for the NIST symmetric key wrap algorithm.

Constructor Detail

AESKeyWrapWithPadding

public AESKeyWrapWithPadding()

Creates a new instance of this AESKeyWrapWithPadding cipher.
Applications should not call this constructor to create a AESKeyWrapWithPadding Cipher object; they should call one of the Cipher.getInstance factory methods instead, e.g.:

 Cipher cipher = Cipher.getInstance("AESKeyWrapWithPadding");
 

Since the AESKeyWrapWithPadding cipher only runs in ECB mode and uses its inherent padding mechanism, any mode or padding specification as part of the transformation string supplied when creating the Cipher object is ignored.

Method Detail

engineSetMode

public void engineSetMode(java.lang.String mode)
                   throws java.security.NoSuchAlgorithmException

Sets the mode of this cipher.

This method only overrides engineSetMode for not allowing an application to request a specific cipher mode (this key wrap cipher always uses "ECB").

Parameters:

mode - the cipher mode; ignored

Throws:

java.security.NoSuchAlgorithmException - if this cipher mode is not supported

See Also:

CipherSpi.engineSetMode(java.lang.String)

engineUpdate

public byte[] engineUpdate(byte[] input,
                  int inputOffset,
                  int inputLen)

Updates this Cipher with the given data bytes. This method only buffers the given bytes to be used for the final wrapping/unwrapping when method wrap/ unwrap is called.

Parameters:

input - the input data as byte array

inputOffset - the start position in the input array

inputLen - the number of bytes that should be processed, starting at inputOffset

Returns:

always null since no output is produced by this method

See Also:

CipherSpi.engineUpdate(byte[], int, int)

engineUpdate

public int engineUpdate(byte[] input,
               int inputOffset,
               int inputLen,
               byte[] output,
               int outputOffset)
                 throws javax.crypto.ShortBufferException

Updates this Cipher with the given data bytes. This method only buffers the given bytes to be used for the final wrapping/unwrapping when method wrap/ unwrap is called.

Parameters:

input - the input data as byte array

inputOffset - the start position in the input array

inputLen - the number of bytes that should be processed, starting at inputOffset

output - the byte array to which to write the result; ignored

outputOffset - the start position in the output array; ignored

Returns:

always 0 since no output is produced by this method

Throws:

javax.crypto.ShortBufferException - never thrown

See Also:

CipherSpi.engineUpdate(byte[], int, int, byte[], int)

engineDoFinal

public byte[] engineDoFinal(byte[] input,
                   int inputOffset,
                   int inputLen)
                     throws javax.crypto.IllegalBlockSizeException,
                            javax.crypto.BadPaddingException

Performs the final step of a en/decryption (wrapping/unwrappin) operation by processing the given input data and any remaining buffered data.

The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. The total length of the input data has to be a multiple of 8 (which is the case for content encryption keys to be wrapped). The result is returned as a output byte array.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

Returns:

the byte array containing the en/decrypted data

Throws:

javax.crypto.IllegalBlockSizeException - if the total length of the processed data is not a multiple of 8

javax.crypto.BadPaddingException - if a padding error occurs

See Also:

CipherSpi.engineDoFinal(byte[], int, int)

engineDoFinal

public int engineDoFinal(byte[] input,
                int inputOffset,
                int inputLen,
                byte[] output,
                int outputOffset)
                  throws javax.crypto.ShortBufferException,
                         javax.crypto.IllegalBlockSizeException,
                         javax.crypto.BadPaddingException

Performs the final step of a en/decryption (wrapping/unwrappin) operation by processing the given input data and any remaining buffered data.

The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. The result is stored in the given output byte array, beginning at outputOffset. The number of bytes stored in this byte array are returned.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

output - the byte array for holding the result

outputOffset - the offset indicating the start position within the output byte array to which the en/decrypted data is written

Returns:

the number of bytes stored in the output byte array

Throws:

javax.crypto.ShortBufferException - if the given output buffer is too small for holding the result

javax.crypto.IllegalBlockSizeException - if the total length of the processed data is not a multiple of 8

javax.crypto.BadPaddingException - if a padding error occurs

See Also:

CipherSpi.engineDoFinal(byte[], int, int, byte[], int)

engineInit

public 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 object with proper key and algorithm parameter values, and some random seed.

Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE), e.g.:

 cipher_obj.init(Cipher.ENCRYPT_MODE, key, alg_params, random_seed);
 

The Cipher init will call the proper CipherSpi engineInit method.

Specified by:

engineInit in class javax.crypto.CipherSpi

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

params - the algorithm parameters

random - the random seed

Throws:

java.security.InvalidKeyException - if the given key cannot be used for initializing this cipher

java.security.InvalidAlgorithmParameterException - if the given algorithm parameters don't match to this cipher

See Also:

Cipher.init(int, java.security.Key), CipherSpi.engineInit(int, java.security.Key, java.security.SecureRandom)

engineInit

public void engineInit(int opmode,
              java.security.Key key,
              java.security.SecureRandom random)
                throws java.security.InvalidKeyException

Initializes this cipher object with a proper key and some random seed.

Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE), e.g.:

 cipher_obj.init(Cipher.ENCRYPT_MODE, key, random_seed);
 

The Cipher init will call the proper CipherSpi engineInit method.

If this cipher (including its underlying feedback or padding scheme) requires any random bytes, it will get them from random.

Specified by:

engineInit in class javax.crypto.CipherSpi

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

random - the random seed

Throws:

java.security.InvalidKeyException - if the given key cannot be used for initializing this cipher

See Also:

Cipher.init(int, java.security.Key), CipherSpi.engineInit(int, java.security.Key, java.security.SecureRandom)

engineInit

public 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 object with proper key and algorithm parameter values, and some random seed.

Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE), e.g.:

 cipher_obj.init(Cipher.ENCRYPT_MODE, key, alg_params, random_seed);
 

The Cipher init will call the proper CipherSpi engineInit method.

Specified by:

engineInit in class javax.crypto.CipherSpi

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

params - the algorithm parameters

random - the random seed

Throws:

java.security.InvalidKeyException - if the given key cannot be used for initializing this cipher

java.security.InvalidAlgorithmParameterException - if the given algorithm parameters don't match to this cipher

See Also:

Cipher.init(int, java.security.Key), CipherSpi.engineInit(int, java.security.Key, java.security.SecureRandom)

engineGetParameters

public java.security.AlgorithmParameters engineGetParameters()

Gets the algorithm parameters used/generated by this Cipher engine.

Specified by:

engineGetParameters in class javax.crypto.CipherSpi

Returns:

the algorithm parameters

engineUpdateAAD

protected void engineUpdateAAD(byte[] src,
                   int offset,
                   int len)

Overrides:

engineUpdateAAD in class javax.crypto.CipherSpi

engineGetOutputSize

public int engineGetOutputSize(int inLen)

Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.

Specified by:

engineGetOutputSize in class javax.crypto.CipherSpi

Parameters:

inLen - the number of bytes to process

Returns:

the size of the output buffer (in bytes)

See Also:

Cipher.getOutputSize(int), CipherSpi.engineGetOutputSize(int)

engineGetIV

public byte[] engineGetIV()

Returns a byte array containing the initialization vector (IV). If the algorithm corresponding to this cipher object does not use an initialization vector, null is returned.

Specified by:

engineGetIV in class javax.crypto.CipherSpi

Returns:

the initialization vector in a byte array if this cipher object operates with an IV and the IV already has been set, null otherwise.

See Also:

Cipher.getIV(), CipherSpi.engineGetIV()

getModeBlockSize

public int getModeBlockSize()

Returns the block size corresponding to the actual cipher mode. This may differ from the actual block size of the cipher in the OFB, CFB and CTR mode. This is the input size that an application must supply to an update call to get an output.

Returns:

The block size (in bytes) of the current mode. This is always at least one.

engineGetBlockSize

public int engineGetBlockSize()

Returns the block size corresponding to this cipher. The block size is returned in bytes. If the implemented algorithm is not a block cipher, 0 is returned.

Specified by:

engineGetBlockSize in class javax.crypto.CipherSpi

Returns:

the block size (in bytes) if this cipher is a block cipher, 0 otherwise.

See Also:

Cipher.getBlockSize(), CipherSpi.engineGetBlockSize()

toString

public java.lang.String toString()

Returns a string representation of this Cipher.

Overrides:

toString in class java.lang.Object

Returns:

a string representation

engineGetKeySize

protected int engineGetKeySize(java.security.Key key)
                        throws java.security.InvalidKeyException

Overrides:

engineGetKeySize in class javax.crypto.CipherSpi

Throws:

java.security.InvalidKeyException

engineWrap

protected byte[] engineWrap(java.security.Key key)
                     throws javax.crypto.IllegalBlockSizeException,
                            java.security.InvalidKeyException

Overrides:

engineWrap in class javax.crypto.CipherSpi

Throws:

javax.crypto.IllegalBlockSizeException

java.security.InvalidKeyException

engineUnwrap

protected java.security.Key engineUnwrap(byte[] wrappedKey,
                             java.lang.String wrappedKeyAlgorithm,
                             int wrappedKeyType)
                                  throws java.security.InvalidKeyException,
                                         java.security.NoSuchAlgorithmException

Overrides:

engineUnwrap in class javax.crypto.CipherSpi

Throws:

java.security.InvalidKeyException

java.security.NoSuchAlgorithmException