com.entrust.toolkit.security.crypto.key

Class X9_63KeyDeriver

java.lang.Object

com.entrust.toolkit.security.crypto.key.X9_63KeyDeriver

public final class X9_63KeyDeriver
extends java.lang.Object

An implementation of the X9.63 Key Derivation algorithm, as defined in ANSI X9.63.

This key derivation algorithm is identical to the X9.42 Key Derivation Function Based on Concatenation. As such, it can be used to represent this algorithm as well. (The two algorithms are mathematically identical; they are simply defined using variables with different names in their respective specifications).

The key derivation function is used to derive keying data from a shared secret bit string. It can be used by key agreement algorithms to compute keying data from a shared secret value; it can also be used with asymmetric encryption algorithms. The X9.63 standard specifies the key derivation function as follows:

Prerequisites:

The prerequisite for the operation of the key derivation function is that an ANSI-approved hash function has been chosen as specified in X9.63 Section 5.6.2 (SHA-1). Let hashlen denote the length of the output of the hash function chosen in bits.

Input:

The input to the key derivation function is:

1. A bit string Z that is the shared secret value.
2. An integer keydatalen that is the length in bits of the keying data to be generated; keydatalen shall be less than hashlen*(232–1).
3. (Optional) A bit string SharedInfo that consists of some data shared by the two entities intended to share the secret value Z
.

Ingredients:

The key derivation function employs one of the hash functions specified in X9.63 Section 5.6.2 (SHA-1).

Actions:

The key derivation function is computed as follows:

1. Initiate a 32-bit, big-endian bit string counter as 0x00000001
2. For i=1 to j=ceiling(keydatalen/hashlen), do the following:
   
   1. Compute Hashi = H(Z || counter || [SharedInfo])
   2. Increment counter
   3. Increment i
3. Let HHashj denote Hashj if keydatalen/hashlen is an integer, and let it denote the (keydatalen - (hashlen*j)) leftmost bits of Hashj otherwise.
4. Set KeyData = Hash1||Hash2||...||Hashj-1||HHashj.

Output:

The bit string KeyData of length keydatalen bits.

The key derivation algorithm may be invoked multiple times for each shared secret value (i.e., the key derivation algorithm is re-invocable). In this case, it is the responsibility of the caller to specify unique values for SharedInfo to ensure that different keying data is produced for each invocation that uses the same shared secret value. For example, consider an application that encrypts data and performs an HMAC calculation, both of which require key data derived using the key derivation algorithm. The key derivation algorithm could initially be invoked with SharedInfo specified as the ASCII encoding of 'TDEA key', followed by a second invocation with SharedInfo specified as the ASCII encoding of 'HMAC key'. However, if the key being derived has an unambiguous use due to context, it is allowed to omit the SharedInfo field.

A single invocation of the key derivation algorithm may be used to produce multiple keys. In this case, the keying data produced by the key derivation algorithm shall be parsed so that no bit in one key is also used as a bit in any other key. For example, the sequence of bits parsed for one key shall not overlap the sequence of bits parsed for another key.

Several APIs are provided that allow key derivation to be carried out using various message digest algorithm implementations as the hash function. However, only message digest algorithm implementations that provide at least 80-bits of security are permitted (produce digests of at least 160-bits).

Note:

This algorithm is NOT implemented under the Java Cryptography Architecture (JCA); doing so is technically possible but defeats the purpose of the JCA (interoperable cryptographic implementations). The JCA was not designed with key derivation algorithms in mind.

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

Since:

7.2

Field Summary

Fields

Modifier and Type	Field and Description
static ObjectID	X942_KD_CONCATENATION_OID Object Identifier for this algorithm as defined in ASNI X9.42.

Method Summary

Methods

Modifier and Type	Method and Description
static byte[]	derive(byte[] sharedSecret, byte[] sharedInfo, int keyLength, java.security.MessageDigest messageDigest) Derives key data according to the X9.63 key derivation algorithm, using the indicated message digest algorithm implementation as the hash function.
static byte[]	derive(byte[] sharedSecret, byte[] sharedInfo, int keyLength, java.lang.String messageDigestAlgorithmName) Derives key data according to the X9.63 key derivation algorithm, using the indicated message digest algorithm as the hash function.
static byte[]	deriveUsingSHA1(byte[] sharedSecret, byte[] sharedInfo, int keyLength) Derives key data according to the X9.63 key derivation algorithm, using the SHA-1 message digest algorithm implementation from the 'Entrust' JCA cryptographic service provider as the hash function.

Methods inherited from class java.lang.Object

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

Field Detail

X942_KD_CONCATENATION_OID

public static final ObjectID X942_KD_CONCATENATION_OID

Object Identifier for this algorithm as defined in ASNI X9.42.

Method Detail

derive

public static byte[] derive(byte[] sharedSecret,
            byte[] sharedInfo,
            int keyLength,
            java.security.MessageDigest messageDigest)

Derives key data according to the X9.63 key derivation algorithm, using the indicated message digest algorithm implementation as the hash function.

FIPS 140-2:

FIPS Service: Key Derivation (primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

sharedSecret - [FIPS 140-2 input output] [FIPS 140-2 CSP] the shared secret

sharedInfo - [FIPS 140-2 input output] the shared information; consists of some data shared by the two entities intended to share the secret value (OPTIONAL)

keyLength - [FIPS 140-2 input output]the length of the key data to be derived in bytes

messageDigest - [FIPS 140-2 control input] the message digest algorithm implementation to be used as the hash function during the key derivation

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the derived key data

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

derive

public static byte[] derive(byte[] sharedSecret,
            byte[] sharedInfo,
            int keyLength,
            java.lang.String messageDigestAlgorithmName)

Derives key data according to the X9.63 key derivation algorithm, using the indicated message digest algorithm as the hash function.

The message digest algorithm implementation is retrieved from the 'Entrust' JCA cryptographic service provider.

FIPS 140-2:

FIPS Service: Key Derivation (primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

sharedSecret - [FIPS 140-2 input output] [FIPS 140-2 CSP] the shared secret

sharedInfo - [FIPS 140-2 input output] the shared information; consists of some data shared by the two entities intended to share the secret value (OPTIONAL)

keyLength - [FIPS 140-2 input output]the length of the key data to be derived in bytes

messageDigestAlgorithmName - [FIPS 140-2 control input] the name of the message digest algorithm to be used as the hash function during the key derivation

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the derived key data

Throws:

java.lang.SecurityException - [FIPS 140-2 status output] if the 'Entrust' JCA cryptographic service provider is not installed or does not support the requested algorithm

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

deriveUsingSHA1

public static byte[] deriveUsingSHA1(byte[] sharedSecret,
                     byte[] sharedInfo,
                     int keyLength)

Derives key data according to the X9.63 key derivation algorithm, using the SHA-1 message digest algorithm implementation from the 'Entrust' JCA cryptographic service provider as the hash function.

FIPS 140-2:

FIPS Service: Key Derivation (primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

sharedSecret - [FIPS 140-2 input output] [FIPS 140-2 CSP] the shared secret

sharedInfo - [FIPS 140-2 input output] the shared information; consists of some data shared by the two entities intended to share the secret value (OPTIONAL)

keyLength - [FIPS 140-2 input output]the length of the key data to be derived in bytes

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the derived key data

Throws:

java.lang.SecurityException - [FIPS 140-2 status output] if the 'Entrust' JCA cryptographic service provider is not installed

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations