keywhiz.hkdf

Class Hkdf

java.lang.Object

keywhiz.hkdf.Hkdf

public class Hkdf
extends Object

HMAC-based Extract-and-Expand Key Derivation Function (HKDF) from RFC-5869. HKDF is a standard means to generate a derived key of arbitrary length.

 // Instantiate an Hkdf object with a hash function.
 Hkdf hkdf = new Hkdf(Hash.SHA256);

 // Using some protected input keying material (IKM), extract a pseudo-random key (PRK) with a
 // random salt. Remember to store the salt so the key can be derived again.
 SecretKey prk = hkdf.extract(Hkdf.randomSalt(), ikm);

 // Expand the prk with some information related to your data and the length of the output key.
 SecretKey derivedKey = hkdf.expand(prk, "id: 5".getBytes(StandardCharsets.UTF_8), 32);
 

HKDF is a generic means for generating derived keys. In some cases, you may want to use it in a different manner. Consult the RFC for security considerations, when to omit a salt, skipping the extraction step, etc.

Method Summary

Modifier and Type	Method and Description
byte[]	expand(SecretKey key, byte[] info, int outputLength) HKDF-Expand(PRK, info, L) -> OKM
SecretKey	extract(SecretKey salt, byte[] ikm) HKDF-Extract(salt, IKM) -> PRK
SecretKey	randomSalt() Generates a random salt value to be used with extract(javax.crypto.SecretKey, byte[]).
static Hkdf	usingDefaults()
static Hkdf	usingHash(Hash hash)
static Hkdf	usingProvider(Provider provider)

Methods inherited from class java.lang.Object

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

Method Detail

usingDefaults

public static Hkdf usingDefaults()

Returns:

Hkdf constructed with default hash and derivation provider

usingHash

public static Hkdf usingHash(Hash hash)

Parameters:

hash - Supported hash function constant

Returns:

Hkdf constructed with a specific hash function

usingProvider

public static Hkdf usingProvider(Provider provider)

Parameters:

provider - provider for key derivation, particularly useful when using HSMs

Returns:

Hkdf constructed with a specific JCE provider for key derivation

extract

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

HKDF-Extract(salt, IKM) -> PRK

Parameters:

salt - optional salt value (a non-secret random value); if not provided, it is set to a string of HashLen zeros.

ikm - input keying material

Returns:

a pseudorandom key (of HashLen bytes)

expand

public byte[] expand(SecretKey key,
                     byte[] info,
                     int outputLength)

HKDF-Expand(PRK, info, L) -> OKM

Parameters:

key - a pseudorandom key of at least HashLen bytes (usually, the output from the extract step)

info - context and application specific information (can be empty)

outputLength - length of output keying material in bytes (<= 255*HashLen)

Returns:

output keying material

randomSalt

public SecretKey randomSalt()

Generates a random salt value to be used with extract(javax.crypto.SecretKey, byte[]).

Returns:

randomly generated SecretKey to use for PRK extraction.