Package at.favre.lib.hkdf

Class HKDF

java.lang.Object

at.favre.lib.hkdf.HKDF

public final class HKDF
extends Object

A standards-compliant implementation of RFC 5869 for HMAC-based Key Derivation Function.

HKDF follows the "extract-then-expand" paradigm, where the KDF logically consists of two modules. The first stage takes the input keying material and "extracts" from it a fixed-length pseudorandom key K. The second stage "expands" the key K into several additional pseudorandom keys (the output of the KDF).

HKDF was first described by Hugo Krawczyk.

This implementation is thread safe without the need for synchronization.

Simple Example:

     byte[] pseudoRandomKey = HKDF.fromHmacSha256().extract(null, lowEntropyInput);
     byte[] outputKeyingMaterial = HKDF.fromHmacSha256().expand(pseudoRandomKey, null, 64);
 

See Also:

RFC 5869, Cryptographic Extraction and Key Derivation: The HKDF Scheme, Wikipedia: HKDF

Method Summary

Modifier and Type	Method	Description
byte[]	expand(byte[] pseudoRandomKey, byte[] info, int outLengthBytes)	Step 2 of RFC 5869 (Section 2.3)
byte[]	expand(SecretKey pseudoRandomKey, byte[] info, int outLengthBytes)	Use this if you require SecretKey types by your security framework.
byte[]	extract(byte[] salt, byte[] inputKeyingMaterial)	Step 1 of RFC 5869 (Section 2.2)
byte[]	extract(SecretKey salt, byte[] inputKeyingMaterial)	Use this if you require SecretKey types by your security framework.
byte[]	extractAndExpand(byte[] saltExtract, byte[] inputKeyingMaterial, byte[] infoExpand, int outLengthByte)	Convenience method for extract & expand in a single method
byte[]	extractAndExpand(SecretKey saltExtract, byte[] inputKeyingMaterial, byte[] infoExpand, int outLengthByte)	Convenience method for extract & expand in a single method
static HKDF	from(HkdfMacFactory macFactory)	Create a new HKDF instance for given macFactory.
static HKDF	fromHmacSha256()	Return a shared instance using HMAC with Sha256.
static HKDF	fromHmacSha512()	Return a shared instance using HMAC with Sha512.

Methods inherited from class java.lang.Object

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

Method Detail

fromHmacSha256

public static HKDF fromHmacSha256()

Return a shared instance using HMAC with Sha256. Even though shared, this instance is thread-safe.

Returns:

HKDF instance

fromHmacSha512

public static HKDF fromHmacSha512()

Return a shared instance using HMAC with Sha512. Even though shared, this instance is thread-safe.

Returns:

HKDF instance

from

public static HKDF from(HkdfMacFactory macFactory)

Create a new HKDF instance for given macFactory.

Parameters:

macFactory - used for HKDF

Returns:

a new instance of HKDF

extract

public byte[] extract(byte[] salt,
                      byte[] inputKeyingMaterial)

Step 1 of RFC 5869 (Section 2.2)

The first stage takes the input keying material and "extracts" from it a fixed-length pseudorandom key K. The goal of the "extract" stage is to "concentrate" and provide a more uniformly unbiased and higher entropy but smaller output. This is done by utilising the diffusion properties of cryptographic MACs.

About Salts (from RFC 5869):

HKDF is defined to operate with and without random salt. This is done to accommodate applications where a salt value is not available. We stress, however, that the use of salt adds significantly to the strength of HKDF, ensuring independence between different uses of the hash function, supporting "source-independent" extraction, and strengthening the analytical results that back the HKDF design.

Parameters:

salt - optional salt value (a non-secret random value) (can be null) if not provided, it is set to an array of hash length of zeros.

inputKeyingMaterial - data to be extracted (IKM)

Returns:

a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand

See Also:

RFC 5869 Section 2.2

extract

public byte[] extract(SecretKey salt,
                      byte[] inputKeyingMaterial)

Use this if you require SecretKey types by your security framework. See also HkdfMacFactory.createSecretKey(byte[]).

See extract(byte[], byte[]) for description.

Parameters:

salt - optional salt value (a non-secret random value) (can be null)

inputKeyingMaterial - data to be extracted (IKM)

Returns:

a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand

expand

public byte[] expand(byte[] pseudoRandomKey,
                     byte[] info,
                     int outLengthBytes)

Step 2 of RFC 5869 (Section 2.3)

To "expand" the generated output of an already reasonably random input such as an existing shared key into a larger cryptographically independent output, thereby producing multiple keys deterministically from that initial shared key, so that the same process may produce those same secret keys safely on multiple devices, as long as the same inputs are used.

About Info (from RFC 5869):

While the 'info' value is optional in the definition of HKDF, it is often of great importance in applications. Its main objective is to bind the derived key material to application- and context-specific information. For example, 'info' may contain a protocol number, algorithm identifiers, user identities, etc. In particular, it may prevent the derivation of the same keying material for different contexts (when the same input key material (IKM) is used in such different contexts).

Parameters:

pseudoRandomKey - a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step)

info - optional context and application specific information; may be null

outLengthBytes - length of output keying material in bytes

Returns:

new byte array of output keying material (OKM)

See Also:

RFC 5869 Section 2.3

expand

public byte[] expand(SecretKey pseudoRandomKey,
                     byte[] info,
                     int outLengthBytes)

Use this if you require SecretKey types by your security framework. See also HkdfMacFactory.createSecretKey(byte[]).

See expand(byte[], byte[], int) for description.

Parameters:

pseudoRandomKey - a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step)

info - optional context and application specific information; may be null

outLengthBytes - length of output keying material in bytes

Returns:

new byte array of output keying material (OKM)

extractAndExpand

public byte[] extractAndExpand(byte[] saltExtract,
                               byte[] inputKeyingMaterial,
                               byte[] infoExpand,
                               int outLengthByte)

Convenience method for extract & expand in a single method

Parameters:

saltExtract - optional salt value (a non-secret random value);

inputKeyingMaterial - data to be extracted (IKM)

infoExpand - optional context and application specific information; may be null

outLengthByte - length of output keying material in bytes

Returns:

new byte array of output keying material (OKM)

extractAndExpand

public byte[] extractAndExpand(SecretKey saltExtract,
                               byte[] inputKeyingMaterial,
                               byte[] infoExpand,
                               int outLengthByte)

Convenience method for extract & expand in a single method

Parameters:

saltExtract - optional salt value (a non-secret random value);

inputKeyingMaterial - data to be extracted (IKM)

infoExpand - optional context and application specific information; may be null

outLengthByte - length of output keying material in bytes

Returns:

new byte array of output keying material (OKM)