com.entrust.toolkit.security.crypto.key

Class SPKMKeyDeriver

java.lang.Object

com.entrust.toolkit.security.crypto.key.SPKMKeyDeriver

public final class SPKMKeyDeriver
extends java.lang.Object

An implementation of the SPKM One-Way Function for Subkey Derivation algorithm, as defined in RFC 2025, The Simple Public-Key GSS-API Mechanism (SPKM) Section 2.4.

It specifies the the derivation algorithm for a k-bit subkey as follows:

 rightmost_k_bits(OWF(context_key || x || n || s || context_key))
 

where

• "x" is the ASCII character "C" (0x43) if the subkey is for a confidentiality algorithm or the ASCII character "I" (0x49) if the subkey is for a keyed integrity algorithm
• "n" is the number of the algorithm in the appropriate agreed list for the context (the ASCII character "0" (0x30), "1" (0x31), and so on)
• "s" is the "stage" of processing -- always the ASCII character "0" (0x30), unless "k" is greater than the output size of OWF, in which case the OWF is computed repeatedly with increasing ASCII values of "stage" (each OWF output being concatenated to the end of previous OWF outputs), until "k" bits have been generated
• "||" is the concatenation operation
• "OWF" is any appropriate One-Way Function

Several APIs are provided that allow the key derivation to be carried out using various message digest algorithm implementations as the OWF. The "x" value corresponds to the subKeyType API parameter, which indicates the the subkey algorithm type. For this parameter, the pre-defined values SUB_KEY_ALGORITHM_CONFIDENTIALITY and SUB_KEY_ALGORITHM_KEYED_INTEGRITY can be used. The "n" value corresponds to the algorithmNumber API parameter, which represents the number of the algorithm in the appropriate agreed list for the context. For this parameter, use an integer (not a byte representing an ASCII encoded character, this conversion will be done internally). The "s" value is set and handled internally; it does not correspond to any API parameter.

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.1sp1

See Also:

RFC 2025, The Simple Public-Key GSS-API Mechanism (SPKM)

Field Summary

Fields

Modifier and Type	Field and Description
static byte	SUB_KEY_ALGORITHM_CONFIDENTIALITY Indicates that the subkey is for a confidentiality algorithm; to be used as a value for the 'x' algorithm parameter (the subKeyType parameter in the key derivation APIs).
static byte	SUB_KEY_ALGORITHM_KEYED_INTEGRITY Indicates that the subkey is for a keyed integrity algorithm; to be used as a value for the 'x' algorithm parameter (the subKeyType parameter in the key derivation APIs).

Method Summary

Methods

Modifier and Type	Method and Description
static byte[]	derive(byte[] contextKey, byte subKeyType, int algorithmNumber, int subKeyLength, java.security.MessageDigest messageDigest) Derives a subkey according to the SPKM subkey derivation algorithm, using the indicated message digest algorithm implementation as the OWF.
static byte[]	derive(byte[] contextKey, byte subKeyType, int algorithmNumber, int subKeyLength, java.lang.String messageDigestAlgorithmName) Derives a subkey according to the SPKM subkey derivation algorithm, using the indicated message digest algorithm as the OWF.
static byte[]	deriveUsingMD5(byte[] contextKey, byte subKeyType, int algorithmNumber, int subKeyLength) Derives a subkey according to the SPKM subkey derivation algorithm, using the MD5 message digest algorithm implementation from the 'Entrust' JCA cryptographic service provider as the OWF.
static byte[]	deriveUsingSHA1(byte[] contextKey, byte subKeyType, int algorithmNumber, int subKeyLength) Derives a subkey according to the SPKM subkey derivation algorithm, using the SHA-1 message digest algorithm implementation from the 'Entrust' JCA cryptographic service provider as the OWF.

Methods inherited from class java.lang.Object

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

Field Detail

SUB_KEY_ALGORITHM_CONFIDENTIALITY

public static final byte SUB_KEY_ALGORITHM_CONFIDENTIALITY

Indicates that the subkey is for a confidentiality algorithm; to be used as a value for the 'x' algorithm parameter (the subKeyType parameter in the key derivation APIs).

See Also:

Constant Field Values

SUB_KEY_ALGORITHM_KEYED_INTEGRITY

public static final byte SUB_KEY_ALGORITHM_KEYED_INTEGRITY

Indicates that the subkey is for a keyed integrity algorithm; to be used as a value for the 'x' algorithm parameter (the subKeyType parameter in the key derivation APIs).

See Also:

Constant Field Values

Method Detail

derive

public static byte[] derive(byte[] contextKey,
            byte subKeyType,
            int algorithmNumber,
            int subKeyLength,
            java.security.MessageDigest messageDigest)

Derives a subkey according to the SPKM subkey derivation algorithm, using the indicated message digest algorithm implementation as the OWF.

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:

contextKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] the context key

subKeyType - [FIPS 140-2 data input] indicates the algorithm the subkey is intended for ( SUB_KEY_ALGORITHM_CONFIDENTIALITY indicates a confidentiality algorithm, SUB_KEY_ALGORITHM_KEYED_INTEGRITY indicates a keyed integrity algorithm)

algorithmNumber - [FIPS 140-2 data input] an integer representing the number of the algorithm in the appropriate agreed list for the context (0, 1, 2, ...)

subKeyLength - [FIPS 140-2 data input] the length of the subkey to be derived in bytes

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

Returns:

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

Throws:

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

derive

public static byte[] derive(byte[] contextKey,
            byte subKeyType,
            int algorithmNumber,
            int subKeyLength,
            java.lang.String messageDigestAlgorithmName)

Derives a subkey according to the SPKM subkey derivation algorithm, using the indicated message digest algorithm as the OWF.

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:

contextKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] the context key

subKeyType - [FIPS 140-2 data input] indicates the algorithm the subkey is intended for ( SUB_KEY_ALGORITHM_CONFIDENTIALITY indicates a confidentiality algorithm, SUB_KEY_ALGORITHM_KEYED_INTEGRITY indicates a keyed integrity algorithm)

algorithmNumber - [FIPS 140-2 data input] an integer representing the number of the algorithm in the appropriate agreed list for the context (0, 1, 2, ...)

subKeyLength - [FIPS 140-2 data input] the length of the subkey to be derived in bytes

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

Returns:

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

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[] contextKey,
                     byte subKeyType,
                     int algorithmNumber,
                     int subKeyLength)

Derives a subkey according to the SPKM subkey derivation algorithm, using the SHA-1 message digest algorithm implementation from the 'Entrust' JCA cryptographic service provider as the OWF.

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:

contextKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] the context key

subKeyType - [FIPS 140-2 data input] indicates the algorithm the subkey is intended for ( SUB_KEY_ALGORITHM_CONFIDENTIALITY indicates a confidentiality algorithm, SUB_KEY_ALGORITHM_KEYED_INTEGRITY indicates a keyed integrity algorithm)

algorithmNumber - [FIPS 140-2 data input] an integer representing the number of the algorithm in the appropriate agreed list for the context (0, 1, 2, ...)

subKeyLength - [FIPS 140-2 data input] the length of the subkey to be derived in bytes

Returns:

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

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

deriveUsingMD5

public static byte[] deriveUsingMD5(byte[] contextKey,
                    byte subKeyType,
                    int algorithmNumber,
                    int subKeyLength)

Derives a subkey according to the SPKM subkey derivation algorithm, using the MD5 message digest algorithm implementation from the 'Entrust' JCA cryptographic service provider as the OWF.

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:

contextKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] the context key

subKeyType - [FIPS 140-2 data input] indicates the algorithm the subkey is intended for ( SUB_KEY_ALGORITHM_CONFIDENTIALITY indicates a confidentiality algorithm, SUB_KEY_ALGORITHM_KEYED_INTEGRITY indicates a keyed integrity algorithm)

algorithmNumber - [FIPS 140-2 data input] an integer representing the number of the algorithm in the appropriate agreed list for the context (0, 1, 2, ...)

subKeyLength - [FIPS 140-2 data input] the length of the subkey to be derived in bytes

Returns:

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

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