iaik.security.cipher

Class TripleDESKeyWrap

java.lang.Object

javax.crypto.CipherSpi

iaik.security.cipher.TripleDESKeyWrap

public class TripleDESKeyWrap
extends javax.crypto.CipherSpi

This class implements the CMS TripleDES key wrap algorithm.

RFC 3217 (Triple-DES and RC2 Key Wrapping) (Section 3.1, 3.2) specifies the TripleDES key wrap algorithm for wrapping TripleDES content encryption keys with TripleDES key encryption keys when using the CMS KeyAgreeRecipientInfo or KEKRecipientInfo choice for providing recipient specific information when encrypting data using the CMS EnvelopedData type.

Since this class only can be used for wrapping/unwrapping secret content encryption keys an application only can call methods wrap and unwrap of the corresponding Cipher object. Any attempt to call a update or doFinal method will cause a RuntimeException to be thrown. A CMS key wrap (unwrap) procedure involves two encryption (decryption) operations, both run in CBC mode. The first encryption step uses a random IV and the second encryption step uses a fixed IV of 0x4adda22c79e82105. Correspondingly the first decryption step uses a fixed IV (0x4adda22c79e82105) and the second decryption step uses the random IV recovered from the first decryption. When calling an engineInit method any parameters supplied are ignored; this CMS TripleDes 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 TripleDES CMS key wrap cipher does not include parameters in its algorithm id.

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

For example, wrapping a Triple-DES content encryption key using a Triple-DES 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 TripleDES key wrap cipher:
 Cipher c = Cipher.getInstance("3DESWrap3DES");
 // 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("3DESWrap3DES");
 // init with the key encryption key
 c.init(Cipher.UNWRAP_MODE, kek);
 // unwrap the wrapped content encryption key:
 Key unwrappedCek = c.unwrap(wrappedCek, "DESede", Cipher.SECRET_KEY);
 

Version:

File Revision 12

Field Summary

Fields

Modifier and Type	Field and Description
protected int	cipherTextLength The expected cipher text length, may be required to be checked.
static byte[]	CMS_KEY_WRAP_IV The IV for the last encryption step of CMS key wrap.
protected java.security.Key	kek The key encryption key (used for en/decrypting the content encryption key).
protected byte[]	keyWrapIV The IV to be used for the second encryption step.
protected java.security.SecureRandom	random The SecureRandom.

Constructor Summary

Constructors

Constructor and Description
TripleDESKeyWrap() Creates a TripleDESKeyWrap object.

Method Summary

Methods

Modifier and Type	Method and Description
static void	checkForOddParity(boolean check) Decides whether to check the unwrapped cek for odd parity.
protected byte[]	computeLCEKPAD(java.security.Key contentEncryptionKey) Calculates the LCEKPAD value (RFC 2630, Section 12.6.4) from the given content encryption key.
protected byte[]	decomposeLCEKPAD(byte[] LCEKPAD) Decomposes the LCEKPAD value (RFC 2630, Section 12.6.5, 8.) into LENGTH CEK and PAD and returns the CEK
byte[]	engineDoFinal(byte[] in, int inOff, int inLen) Throws a RuntimeException since not supported by this key wrap cipher.
int	engineDoFinal(byte[] in, int inOff, int inLen, byte[] out, int outOff) Throws a RuntimeException since not supported by this key wrap cipher.
int	engineGetBlockSize() Returns the block size corresponding to this cipher.
byte[]	engineGetIV() Returns null.
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() Returns null.
void	engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this cipher object.
void	engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random) Initializes this cipher object.
protected void	engineInit(int opmode, java.security.Key key, byte[] iv, java.security.SecureRandom random) Internal inits the underlying TripleDES cipher for the second en/decryption step.
void	engineInit(int opmode, java.security.Key key, java.security.SecureRandom random) Initializes this cipher object.
void	engineSetMode(java.lang.String mode) Sets the mode of this cipher to "CBC".
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) Unwraps the given wrapped key to recover the content encryption key.
byte[]	engineUpdate(byte[] in, int inOff, int inLen) Throws a RuntimeException since not supported by this key wrap cipher.
int	engineUpdate(byte[] in, int inOff, int inLen, byte[] out, int outOff) Throws a RuntimeException since not supported by this key wrap cipher.
protected void	engineUpdateAAD(byte[] src, int offset, int len)
protected byte[]	engineWrap(java.security.Key key)
protected java.security.Key	finishUnWrap(byte[] decryptedCek, java.lang.String wrappedKeyAlgorithm, int wrappedKeyType) Finishes the unwrapping process by checking if the recovered TripleDES content-encryption key is (odd) parity adjusted.
int	getModeBlockSize() Returns the block size corresponding to the actual cipher mode.
protected java.security.SecureRandom	getRandom() Gets the SecureRandom.
protected byte[]	prepareWrap(java.security.Key contentEncryptionKey) Prepares the given content encryption TripleDes key for being wrapped.
java.lang.String	toString() Returns a string representation of this Cipher.

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

kek

protected java.security.Key kek

The key encryption key (used for en/decrypting the content encryption key). To be supplied when initializing the cipher.

cipherTextLength

protected int cipherTextLength

The expected cipher text length, may be required to be checked.

random

protected java.security.SecureRandom random

The SecureRandom.

keyWrapIV

protected byte[] keyWrapIV

The IV to be used for the second encryption step. (default 0x4adda22c79e82105)

CMS_KEY_WRAP_IV

public static final byte[] CMS_KEY_WRAP_IV

The IV for the last encryption step of CMS key wrap. See RFC 2630, section 12.6.2 - 12.6.5:

 IV = 0x4adda22c79e82105.
 

Constructor Detail

TripleDESKeyWrap

public TripleDESKeyWrap()

Creates a TripleDESKeyWrap object. This constructor is only internally used for initializing a TripleDESKeyWrap Cipher. Applications should not call this constructor to get a TripleDESKeyWrap Cipher; they should call one of the Cipher.getInstance factory methods instead, e.g.:

 Cipher tripleDESKeyWrap = Cipher.getInstance("3DESWrap3DES");
 

Since the TripleDESKeyWrap cipher only runs in CBC mode and only is used for wrapping/unwrapping TripleDES content encryption keys, any mode or padding specification as part of the transformation string supplied when creating the Cipher object is ignored.

Method Detail

checkForOddParity

public static final void checkForOddParity(boolean check)

Decides whether to check the unwrapped cek for odd parity. As last step of the unwrap procedure, the unwrapped cek has to be checked for odd parity. However, some applications may not have properly parity adjusted the key on the sending side. This method allows an application to switch off parity checking of the unwrapped cek. Note that checking for odd parity is required by the specification!

Parameters:

check - true to check for odd parity (default), false to not check for odd parity

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.

If parameters are supplied they are ignored. If the cipher has to be initialized for key wrap, a random IV is used. If the cipher has to be initialized for key unwrap, a fixed CMS key wrap IV is used.

Parameters:

opmode - the operation mode for which this cipher is used (WRAP_MODE or UNWRAP_MODE)

key - the key encryption key to be used

params - the algorithm parameters; ignored

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.AlgorithmParameters params,
              java.security.SecureRandom random)
                throws java.security.InvalidKeyException,
                       java.security.InvalidAlgorithmParameterException

Initializes this cipher object.

If parameters are supplied they are ignored. If the cipher has to be initialized for key wrap, a random IV is used. If the cipher has to be initialized for key unwrap, a fixed CMS key wrap IV is used.

Parameters:

opmode - the operation mode for which this cipher is used (WRAP_MODE or UNWRAP_MODE)

key - the key encryption key

params - the algorithm parameters; ignored

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

protected void engineInit(int opmode,
              java.security.Key key,
              byte[] iv,
              java.security.SecureRandom random)
                   throws java.security.InvalidKeyException,
                          java.security.InvalidAlgorithmParameterException

Internal inits the underlying TripleDES cipher for the second en/decryption step.

A CMS key wrap (unwrap) procedure involves two encryption (decryption) operations, both run in CBC mode. The first encryption step uses a random IV and the second encryption step uses a fixed IV of default 0x4adda22c79e82105. Correspondingly the first decryption step uses a fixed IV (default 0x4adda22c79e82105) and the second decryption step uses the random IV recovered from the first decryption. This method is called during the wrapping/unwrapping procedure to init the underlying TripleDES cipher for the second en/decryption step with the given key and iv.

Parameters:

opmode - the operation mode

key - the key encryption key

iv - the initialization vector, either fixed (for second encryption step) or recovered random (for second decryption step)

random - the random seed

Throws:

java.security.InvalidKeyException - if something is wrong with the key

java.security.InvalidAlgorithmParameterException - if an error occurs when creating the parameters from the iv

prepareWrap

protected byte[] prepareWrap(java.security.Key contentEncryptionKey)
                      throws java.security.InvalidKeyException

Prepares the given content encryption TripleDes key for being wrapped.

If the supplied key is a 2-key TripleDES key it is "expanded" to a 3-key TripleDES key by "append" a third key with the same value as the first key. The 3-key TripleDES key then is parity adjusted (odd parity).

Parameters:

contentEncryptionKey - the TripleDES content encryption key to be prepared

Returns:

the content encryption key prepared for being wrapped

Throws:

java.security.InvalidKeyException - if the cek cannot be prepared for some reason

finishUnWrap

protected java.security.Key finishUnWrap(byte[] decryptedCek,
                             java.lang.String wrappedKeyAlgorithm,
                             int wrappedKeyType)
                                  throws java.security.InvalidKeyException

Finishes the unwrapping process by checking if the recovered TripleDES content-encryption key is (odd) parity adjusted.

Parameters:

decryptedCek - the decrypted content encryption key resulting from step 6 (section 3.2 of RFC 3217)

wrappedKeyAlgorithm - the algorithm of the wrapped key, "DESede" (ignored)

wrappedKeyType - only Cipher.SECRET_KEY allowed for this key wrap cipher

Returns:

the unwrapped content encryption key

Throws:

java.security.InvalidKeyException - if the recovered TripleDES content-encryption key is not (odd) parity adjusted.

engineInit

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

Initializes this cipher object.

If the cipher has to be initialized for key wrap, a random IV is used. If the cipher has to be initialized for key unwrap, a fixed CMS key wrap IV is used.

Parameters:

opmode - the operation mode for which this cipher is used (WRAP_MODE or UNWRAP_MODE)

key - the key encryption key to be used

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)

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 (this key wrap cipher itself takes care for padding).

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 to "CBC".

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

Parameters:

mode - the cipher mode

Throws:

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

See Also:

CipherSpi.engineSetMode(java.lang.String)

engineUpdate

public byte[] engineUpdate(byte[] in,
                  int inOff,
                  int inLen)

Throws a RuntimeException since not supported by this key wrap cipher. Use method wrap/unwrap for wrapping/unwrapping a key.

Parameters:

in - the input data.

inOff - the offset indicating where the subarray starts in the in array.

inLen - the length of the subarray.

Returns:

array containing the en/decrypted data

See Also:

BufferedCipher.engineDoFinal(byte[], int, int, byte[], int), Cipher.doFinal(), Cipher.update(byte[]), CipherSpi.engineUpdate(byte[], int, int)

engineUpdate

public int engineUpdate(byte[] in,
               int inOff,
               int inLen,
               byte[] out,
               int outOff)
                 throws javax.crypto.ShortBufferException

Throws a RuntimeException since not supported by this key wrap cipher. Use method wrap/unwrap for wrapping/unwrapping a key.

Parameters:

in - the input data.

inOff - the offset indicating where the subarray starts in the in array.

inLen - the length of the subarray.

out - the output buffer.

outOff - the offset indicating where to start writing the result into the output buffer.

Returns:

number of bytes written to out array.

Throws:

javax.crypto.ShortBufferException - if the buffer size is to short

See Also:

BufferedCipher.engineDoFinal(byte[], int, int, byte[], int), Cipher.doFinal(), Cipher.update(byte[]), CipherSpi.engineUpdate(byte[], int, int)

engineDoFinal

public int engineDoFinal(byte[] in,
                int inOff,
                int inLen,
                byte[] out,
                int outOff)
                  throws javax.crypto.ShortBufferException,
                         javax.crypto.IllegalBlockSizeException,
                         javax.crypto.BadPaddingException

Throws a RuntimeException since not supported by this key wrap cipher. Use method wrap/unwrap for wrapping/unwrapping a key.

Parameters:

in - the byte array holding the data to be processed

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

inLen - the number of bytes to be processed

out - the byte array for holding the result

outOff - 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 the block size for a (no padding performing) block cipher

javax.crypto.BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

See Also:

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

engineDoFinal

public byte[] engineDoFinal(byte[] in,
                   int inOff,
                   int inLen)
                     throws javax.crypto.IllegalBlockSizeException,
                            javax.crypto.BadPaddingException

Throws a RuntimeException since not supported by this key wrap cipher. Use method wrap/unwrap for wrapping/unwrapping a key.

Parameters:

in - the byte array holding the data to be processed

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

inLen - 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 the block size for a (no padding performing) block cipher

javax.crypto.BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

See Also:

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

engineGetParameters

public java.security.AlgorithmParameters engineGetParameters()

Returns null. This method always returns null (CMS key wrap uses fixed IVs) and may be overridden if required for a particular key wrap cipher.

Returns:

null

engineGetIV

public byte[] engineGetIV()

Returns null. This method always returns null (CMS key wrap uses fixed IVs) and may be overridden if required for a particular key wrap cipher.

Returns:

null

See Also:

Cipher.getIV(), CipherSpi.engineGetIV()

toString

public java.lang.String toString()

Returns a string representation of this Cipher.

Returns:

a string representation

engineWrap

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

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

Unwraps the given wrapped key to recover the content encryption key.

This method implements the core operations common to the Triple-DES and RC2 Key Wrap algorithms of RFC 2630, in particular the equivalent steps 1 to 7 of Triple-DES Key Unwrap (section 12.6.3 of RFC 2630) respectively steps 1 to 7 of RC2 Key Unwrap (section 12.6.5 of RFC 2630). Any key wrap algorithm specific operations required to finish the unwrap procedure may be done by implementing the abstract method finishUnWrap for the specific key wrap algorithm in mind. Triple-DES Key wrap, for instance, requires the content encryption key to be (odd) parity adjusted before being wrapped. Triple-DES Key Wrap is implemented by class TripleDESKeyWrap which implements method finishUnWrap to check odd parity at the end of the unwrapping procedure.

Parameters:

wrappedKey - the wrapped content encryption key to be unwrapped

wrappedKeyAlgorithm - the content encryption key algorithm

wrappedKeyType - the key type, Cipher.SECRET_KEY

Throws:

java.security.InvalidKeyException - if an error occurs while unwrapping the key

java.security.NoSuchAlgorithmException - if the algorithm used is not supported by the installed providers

getRandom

protected java.security.SecureRandom getRandom()

Gets the SecureRandom.

If no SecureRandom has been set, a new one is created.

Returns:

the SecureRandom

computeLCEKPAD

protected byte[] computeLCEKPAD(java.security.Key contentEncryptionKey)

Calculates the LCEKPAD value (RFC 2630, Section 12.6.4) from the given content encryption key.

As first step of the RC2 Key Wrap algorithm described in RFC2630, the content-encryption key is concatenated with its length and padded to a multiple of 8, if required:

1. Let the content-encryption key be called CEK, and let the length of the content-encryption key in octets be called LENGTH. LENGTH is a single octet.
2. Let LCEK = LENGTH || CEK.
3. Let LCEKPAD = LCEK || PAD. If the length of LCEK is a multiple of 8, the PAD has a length of zero. If the length of LCEK is not a multiple of 8, then PAD contains the fewest number of random octets to make the length of LCEKPAD a multiple of 8.
4. ...

The LCEKPAD value subsequently is the input to the wrapping process itself. Since LCEKPAD also may be required by other key wrap algorithms than RC2 (e.g. CAST-128 Key Wrap; RFC2984) this method may be used for calculating the LCEKPAD value when preparing the content encryption key for the wrapping procedure.

Parameters:

contentEncryptionKey - the content encryption key for which to calculate the LCEKPAD value

Returns:

the LCEKPAD value calculated from the given content encryption key

decomposeLCEKPAD

protected byte[] decomposeLCEKPAD(byte[] LCEKPAD)
                           throws javax.crypto.BadPaddingException

Decomposes the LCEKPAD value (RFC 2630, Section 12.6.5, 8.) into LENGTH CEK and PAD and returns the CEK

As last step of the RC2 Key UnWrap algorithm described in RFC2630, the LCEKPAD (composed of cek-length, decrypted content-encryption key and optional padding) has to be decomposed for getting the cek. Since LCEKPAD also may be used by other key wrap algorithms than RC2 (e.g. CAST-128 Key Wrap; RFC2984) this method may be used for decomposing the LCEKPAD value when finishing the unwrapping procedure.

Parameters:

LCEKPAD - the LCEKPAD value (LENGTH || CEK || PAD)

Returns:

the recovered raw content encryption key encoding

Throws:

javax.crypto.BadPaddingException - if the PAD value of the LCEKPAD has a length not shorter than 8

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)

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

engineGetKeySize

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

Overrides:

engineGetKeySize in class javax.crypto.CipherSpi

Throws:

java.security.InvalidKeyException