iaik.security.cipher

Class CamelliaKeyWrap

java.lang.Object

javax.crypto.CipherSpi

iaik.security.cipher.CamelliaKeyWrap

public class CamelliaKeyWrap
extends javax.crypto.CipherSpi

This class implements the Camellia key wrap algorithm.

RFC 3657 (Use of the Camellia Encryption Algorithm in CMS) specifies the Camellia key wrap algorithm to maybe used for wrapping Camellia content encryption keys with Camellia key encryption keys.

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

When creating a new Camellia key wrap Cipher object you only may provide the name of the key wrap cipher ("CamelliaWrapCamellia"). Any cipher mode (always uses ECB) or padding (the input data has always be a multiple of 8) specification is ignored.

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

 // the content encryption key to be wrapped:
 SecretKey cek = ...;
 // the key encryption key to be used:
 SecretKey kek = ...;
 // get a Camellia key wrap cipher:
 Cipher c = Cipher.getInstance("CamelliaWrapCamellia", "IAIK");
 // init with the key encryption key
 c.init(Cipher.WRAP_MODE, kek);
 // wrap the content encryption key:
 byte[] wrappedCek = c.wrap(cek);
 

For unwrapping the key init the Cipher in unwrap mode:

 Cipher c = Cipher.getInstance("CamelliaWrapCamellia", "IAIK");
 // init with the key encryption key
 c.init(Cipher.UNWRAP_MODE, kek);
 // unwrap the wrapped content encryption key:
 Key unwrappedCek = c.unwrap(wrappedCek, "Camellia", 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.

Version:

File Revision 1

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
CamelliaKeyWrap() Creates a new instance of this CamelliaKeyWrap 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.
void	engineSetPadding(java.lang.String paddingName) Sets the padding scheme 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 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 javax.crypto.CipherSpi

engineDoFinal, engineUpdate, engineUpdateAAD, 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

CamelliaKeyWrap

public CamelliaKeyWrap()

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

 Cipher CamelliaKeyWrap = Cipher.getInstance("CamelliaWrapCamellia");
 

Since the CamelliaKeyWrap cipher only runs in ECB mode and only is used for wrapping/unwrapping (Camellia content encryption keys) purposes, any mode or padding specification as part of the transformation string supplied when creating the Cipher object is ignored.

Method Detail

engineSetPadding

public void engineSetPadding(java.lang.String paddingName)
                      throws javax.crypto.NoSuchPaddingException

Sets the padding scheme of this cipher.

This method only overrides engineSetPadding for not allowing an application to request a specific padding scheme (the input data always has to be a multiple of 8).

Parameters:

paddingName - the name of the padding scheme; ignored

Throws:

javax.crypto.NoSuchPaddingException - if this padding scheme is not supported

See Also:

CipherSpi.engineSetPadding(java.lang.String)

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

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

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