at.favre.lib.crypto

Class HKDF

java.lang.Object

at.favre.lib.crypto.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 and Description
byte[]	expand(byte[] pseudoRandomKey, byte[] info, int outLengthBytes) Step 1 of RFC 5869 (Section 2.3)
byte[]	extract(byte[] salt, byte[] inputKeyingMaterial) Step 1 of RFC 5869 (Section 2.2)
byte[]	extractAndExpand(byte[] 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 thou shared, this instance is thread-safe.

Returns:

HKDF instance

fromHmacSha512

public static HKDF fromHmacSha512()

Return a shared instance using HMAC with Sha512. Even thou 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);

inputKeyingMaterial - data to be extracted (IKM) if not provided, it is set to a array of hash length of zeros.

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

expand

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

Step 1 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 utilised.

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

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)