Package com.yahoo.security

Class HKDF

java.lang.Object
com.yahoo.security.HKDF
public final class HKDF extends Object
Implementation of RFC-5869 HMAC-based Extract-and-Expand Key Derivation Function (HKDF).

The HKDF is initialized ("extracted") from a (non-secret) salt and a secret key. From this, any number of secret keys can be derived ("expanded") deterministically.

When multiple keys are to be derived from the same initial keying/salting material, each separate key should use a distinct "context" in the expand(int, byte[]) call. This ensures that there exists a domain separation between the keys. Using the same context as another key on a HKDF initialized with the same salt+key results in the exact same derived key material as that key.

This implementation only offers HMAC-SHA256-based key derivation.

Author:
vekterli
See Also:

  • Field Details

  • Method Details

    • pseudoRandomKey

      public byte[] pseudoRandomKey()
      Returns:
      the computed pseudo-random key (PRK) used as input for each expand() call.

    • ofPseudoRandomKey

      public static HKDF ofPseudoRandomKey(byte[] prk)
      Returns:
      a new HKDF instance initially keyed with the given PRK

    • extractedFrom

      public static HKDF extractedFrom(byte[] salt, byte[] ikm)
      Creates and returns a new HKDF instance extracted from the given salt and key.

      Both the salt and input key value may be of arbitrary size, but it is recommended to have both be at least 16 bytes in size.

      Parameters:
      salt - a non-secret salt value. Should ideally be high entropy and functionally "as if random". May not be empty, use unsaltedExtractedFrom(byte[]) if unsalted extraction is desired (though this is not recommended).
      ikm - secret initial Input Keying Material value.
      Returns:
      a new HKDF instance ready for deriving keys based on the salt and IKM.

    • unsaltedExtractedFrom

      public static HKDF unsaltedExtractedFrom(byte[] ikm)
      Creates and returns a new unsalted HKDF instance extracted from the given key.

      Prefer using the salted extractedFrom(byte[], byte[]) method if possible.

      Parameters:
      ikm - secret initial Input Keying Material value.
      Returns:
      a new HKDF instance ready for deriving keys based on the IKM and an all-zero salt.

    • expand

      public byte[] expand(int wantedBytes, byte[] context)
      Derives a key with a given number of bytes for a particular context. The returned key is always deterministic for a given unique context and a HKDF initialized with a specific salt+IKM pair.

      Thread safety: multiple threads can safely call expand() simultaneously on the same HKDF object.

      Parameters:
      wantedBytes - Positive number of output bytes. Must be less than or equal to MAX_OUTPUT_SIZE
      context - Context for key derivation. Derivation is deterministic for a given context. Note: this maps to the "info" field in RFC-5869.
      Returns:
      A byte buffer of size wantedBytes filled with derived key material

    • expand

      public byte[] expand(int wantedBytes)
      Derives a key with a given number of bytes. The returned key is always deterministic for a HKDF initialized with a specific salt+IKM pair.

      If more than one key is to be derived, use expand(int, byte[])

      Thread safety: multiple threads can safely call expand() simultaneously on the same HKDF object.

      Parameters:
      wantedBytes - Positive number of output bytes. Must be less than or equal to MAX_OUTPUT_SIZE
      Returns:
      A byte buffer of size wantedBytes filled with derived key material