org.forgerock.util.crypto

Class HKDFKeyGenerator

java.lang.Object

org.forgerock.util.crypto.HKDFKeyGenerator

public final class HKDFKeyGenerator
extends Object

Implements the HKDF key deriviation function to allow a single input key to be expanded into multiple component keys.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HKDFKeyGenerator.HKDFMasterKey A secret key designed to be used as the master key for HKDF key generation.

Field Summary

Fields

Modifier and Type	Field and Description
static int	HASH_BYTES_LEN The HMAC output length in bytes.
static String	HMAC_ALGORITHM The HMAC algorithm.

Method Summary

Modifier and Type	Method and Description
static Key	expandKey(Key masterKey, String outputKeyAlgorithm, byte[] info, int outputKeySize) Expands a master key into a derived key for a specific purpose.
static Key	expandKey(Key masterKey, String outputKeyAlgorithm, int outputKeySize) Expands a master key into a derived key for a specific purpose.
static Key	expandKey(Key masterKey, String outputKeyAlgorithm, String purpose, int outputKeySize) Expands a master key into a derived key for a specific purpose.
static HKDFKeyGenerator.HKDFMasterKey	extractMasterKey(byte[] inputKeyMaterial) The HKDF "extract" phase that generates a master key from some input key material.
static HKDFKeyGenerator.HKDFMasterKey	extractMasterKey(byte[] inputKeyMaterial, byte[] salt) The HKDF "extract" phase that generates a master key from some input key material.

Methods inherited from class java.lang.Object

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

Field Detail

HMAC_ALGORITHM

public static final String HMAC_ALGORITHM

The HMAC algorithm.

See Also:

Constant Field Values

HASH_BYTES_LEN

public static final int HASH_BYTES_LEN

The HMAC output length in bytes.

See Also:

Constant Field Values

Method Detail

extractMasterKey

public static HKDFKeyGenerator.HKDFMasterKey extractMasterKey(byte[] inputKeyMaterial)

The HKDF "extract" phase that generates a master key from some input key material. This method adds 128-bits of random salt to the derived key. This master key should not be used directly, but instead fed into HKDFKeyGenerator.expandKey(Key, String, String, int) to derive a specific key for a particular usage.

Parameters:

inputKeyMaterial - the input master key material.

Returns:

the derived master key.

extractMasterKey

public static HKDFKeyGenerator.HKDFMasterKey extractMasterKey(byte[] inputKeyMaterial,
                                                              byte[] salt)

The HKDF "extract" phase that generates a master key from some input key material. This method uses the random salt value passed as a parameter. This master key should not be used directly, but instead fed into HKDFKeyGenerator.expandKey(Key, String, String, int) to derive a specific key for a particular usage.

Parameters:

inputKeyMaterial - the input master key material.

salt - the random salt to use when deriving the master key. Should be at least 128 bits and uniformly random.

Returns:

the derived master key.

expandKey

public static Key expandKey(Key masterKey,
                            String outputKeyAlgorithm,
                            String purpose,
                            int outputKeySize)

Expands a master key into a derived key for a specific purpose. The key is derived by repeatedly applying HMAC-SHA-256 using the master key as the key and the given parameters (together with an incrementing counter) as input.

Parameters:

masterKey - the HKDF master key.

outputKeyAlgorithm - the algorithm for which the derived key is to be used, e.g. "AES".

purpose - an arbitrary application-specific string describing the purpose of this key (e.g. "OpenID Connect token signing".

outputKeySize - the output key size, in bytes. This can be between 0 and 8160 bytes.

Returns:

the derived key.

expandKey

public static Key expandKey(Key masterKey,
                            String outputKeyAlgorithm,
                            byte[] info,
                            int outputKeySize)

Expands a master key into a derived key for a specific purpose. The key is derived by repeatedly applying HMAC-SHA-256 using the master key as the key and the given parameters (together with an incrementing counter) as input.

Parameters:

masterKey - the HKDF master key.

outputKeyAlgorithm - the algorithm for which the derived key is to be used, e.g. "AES".

info - an arbitrary application-specific byte-string to include in the key derivation.

outputKeySize - the output key size, in bytes. This can be between 0 and 8160 bytes.

Returns:

the derived key.

expandKey

public static Key expandKey(Key masterKey,
                            String outputKeyAlgorithm,
                            int outputKeySize)

Expands a master key into a derived key for a specific purpose. The key is derived by repeatedly applying HMAC-SHA-256 using the master key as the key and the given parameters (together with an incrementing counter) as input. This is identical to the HKDFKeyGenerator.expandKey(Key, String, String, int) method except that the outputKeyAlgorithm is also used as the purpose when deriving the key.

Parameters:

masterKey - the HKDF master key.

outputKeyAlgorithm - the algorithm for which the derived key is to be used, e.g. "AES".

outputKeySize - the output key size, in bytes. This can be between 0 and 8160 bytes.

Returns:

the derived key.