// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. package com.yahoo.security; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.ByteBuffer; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Objects; /** * 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 {@link #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.
* * @see RFC-5869 * @see HKDF on Wikipedia * * @author vekterli */ public final class HKDF { private static final int HASH_LEN = 32; // Fixed output size of HMAC-SHA256. Corresponds to HashLen in the spec private static final byte[] EMPTY_BYTES = new byte[0]; private static final byte[] ALL_ZEROS_SALT = new byte[HASH_LEN]; public static final int MAX_OUTPUT_SIZE = 255 * HASH_LEN; private final byte[] pseudoRandomKey; // Corresponds to "PRK" in spec private HKDF(byte[] pseudoRandomKey) { this.pseudoRandomKey = pseudoRandomKey; } private static Mac createHmacSha256() { try { return Mac.getInstance("HmacSHA256"); } catch (NoSuchAlgorithmException e) { throw new RuntimeException(e); } } /** * @return the computed pseudo-random key (PRK) used as input for eachexpand()
call.
*/
public byte[] pseudoRandomKey() {
return this.pseudoRandomKey;
}
/**
* @return a new HKDF instance initially keyed with the given PRK
*/
public static HKDF ofPseudoRandomKey(byte[] prk) {
return new HKDF(prk);
}
private static SecretKeySpec hmacKeyFrom(byte[] rawKey) {
return new SecretKeySpec(rawKey, "HmacSHA256");
}
private static Mac createKeyedHmacSha256(byte[] rawKey) {
var hmac = createHmacSha256();
try {
hmac.init(hmacKeyFrom(rawKey));
} catch (InvalidKeyException e) {
throw new RuntimeException(e);
}
return hmac;
}
private static void validateExtractionParams(byte[] salt, byte[] ikm) {
Objects.requireNonNull(salt);
Objects.requireNonNull(ikm);
if (ikm.length == 0) {
throw new IllegalArgumentException("HKDF extraction IKM array can not be empty");
}
if (salt.length == 0) {
throw new IllegalArgumentException("HKDF extraction salt array can not be empty");
}
}
/**
* 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.
* * @param salt a non-secret salt value. Should ideally be high entropy and functionally * "as if random". May not be empty, use {@link #unsaltedExtractedFrom(byte[])} * if unsalted extraction is desired (though this is not recommended). * @param ikm secret initial Input Keying Material value. * @return a new HKDF instance ready for deriving keys based on the salt and IKM. */ public static HKDF extractedFrom(byte[] salt, byte[] ikm) { validateExtractionParams(salt, ikm); /* RFC-5869, Step 2.2, Extract: HKDF-Extract(salt, IKM) -> PRK Options: Hash a hash function; HashLen denotes the length of the hash function output in octets Inputs: 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 Output: PRK a pseudorandom key (of HashLen octets) The output PRK is calculated as follows: PRK = HMAC-Hash(salt, IKM) */ var mac = createKeyedHmacSha256(salt); // Note: HKDF is initially keyed on the salt, _not_ on ikm! mac.update(ikm); return new HKDF(/*PRK = */ mac.doFinal()); } /** * Creates and returns a new unsalted HKDF instance extracted from the given key. * *Prefer using the salted {@link #extractedFrom(byte[], byte[])} method if possible.
* * @param ikm secret initial Input Keying Material value. * @return a new HKDF instance ready for deriving keys based on the IKM and an all-zero salt. */ public static HKDF unsaltedExtractedFrom(byte[] ikm) { return extractedFrom(ALL_ZEROS_SALT, ikm); } /** * 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.
If more than one key is to be derived, use {@link #expand(int, byte[])}
* *Thread safety: multiple threads can safely call expand()
simultaneously
* on the same HKDF object.