iaik.security.cipher

Class HMACwithAESwrap

java.lang.Object

javax.crypto.CipherSpi

iaik.security.cipher.AESKeyWrap

iaik.security.cipher.HMACwithAESwrap

public class HMACwithAESwrap
extends AESKeyWrap

This class implements the HMACwithAESwrap algorithm.

RFC 3537 specifies the HMACwithAESwrap key wrap algorithm for wrapping a HMAC message authentication code key with a AES key encryption key. This algorithm may be used for wrapping HMAC keys as required by the CMS (Cryptographic Message Syntax) AuthenticatedData type.

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

When creating a new CMS HMACwithAESwrap Cipher object you only may provide the name of the key wrap cipher ("AESwrapHMAC"). Any cipher mode (always uses CBC) or padding (does the padding itself) specification is ignored.

For example, wrapping a HMAC key using an AES key encryption key typically may be done as follows:

 // the HMAC key to be wrapped:
 SecretKey hmacKey = ...;
 // the key encryption key to be used:
 SecretKey kek = ...;
 // get a HMACwithAESwrap cipher:
 Cipher c = Cipher.getInstance("AESwrapHMAC");
 // init with the key encryption key
 c.init(Cipher.WRAP_MODE, kek);
 // wrap the HMAC key:
 byte[] wrappedHmacKey = c.wrap(hmacKey);
 

For unwrapping the key init the Cipher in unwrap mode:

 Cipher c = Cipher.getInstance("AESwrapHMAC");
 // init with the key encryption key
 c.init(Cipher.UNWRAP_MODE, kek);
 // unwrap the wrapped HMAC key:
 Key unwrappedHmacKey = c.unwrap(wrappedHmacKey, "HmacSHA1", Cipher.SECRET_KEY);
 

Version:

File Revision 2

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
HMACwithAESwrap() Creates a new instance of this HMACwithAESwrap 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/unwrapping) 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

HMACwithAESwrap

public HMACwithAESwrap()

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

 Cipher c = Cipher.getInstance("AESwrapHMAC");
 

Method Detail

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/unwrapping) 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. In encryption/wrap mode the input data (encoded HMAC key) is padded if it is not a multiple of 8 bytes); in decryption/unwrap mode the padding is removed again.

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 - should not occur since the data is padded automatically

javax.crypto.BadPaddingException - if the encrypted/wrappped data is incorrectly padded

See Also:

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

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 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