iaik.security.kdf

Class HKDF

java.lang.Object

javax.crypto.KeyGeneratorSpi

iaik.security.kdf.HKDF

Direct Known Subclasses:

HKDF.HKDFwithSHA1, HKDF.HKDFwithSHA224, HKDF.HKDFwithSHA256, HKDF.HKDFwithSHA384, HKDF.HKDFwithSHA512

public abstract class HKDF
extends javax.crypto.KeyGeneratorSpi

This class implements the HKDF key derivation function as specified by RFC 5869.

HKDF is a HMAC-based key derivation function, see RFC 5869. It is an "extract-then-expand" key derivation function which first "extracts" a pseudorandom key of fixed length from the input keying material and then "expands" this key to the output keying material of the desired length.
If the input already represents a good pseudorandom key (prk) the extract operation maybe omitted to immediately perform the expand operation.

The intended usage of the HKDF key derivation function is to derive secret keys of extended cryptographic strength from some initial input keying material like, for instance, the output of a Diffie Hellman key exchange protocol. HKDF is NOT intended to derive cryptographic strong keys from sources of low entropy like, for instance, a password. For that purpose a special password based key derivation like PKCS#5 PBKDF2 shall be used.

The inputs to the HKDF key derivation function are input keying material (IKM), a salt value, a context and application specific information string, and the length of the output keying material to be derived. Salt and info string are optional; if not provided they are set to a strings of hashLen zeros and a zero-length string, respectively.

For using HKDF to derive a secret key first create a HKDF KeyGenerator instance, then initialize it with a HKDFParameterSpec and finally generate the secret key. e.g.:

 // the salt:
 byte[] salt = ...;
 // the input keying material:
 byte[] ikm = ...;
 // the info string:
 byte[] info = ...;
 // the length of the output key:
 byte[] l = ...;
 // create a HKDF KeyGenerator for the desired hash function:
 KeyGenerator hkdf = KeyGenerator.getInstance("HKDFwithSHA256");
 // initialize the HKDF:
 HKDFParameterSpec hkdfParamSpec = new HKDFParameterSpec(salt, ikm, info, L);
 hkdf.init(hkdfParamSpec, null);
 // generate the key:
 SecretKey key = hkdf.generateKey(); 
 

If the input already represents a good pseudorandom key (prk) and you only want to perform the expand operation, you may initialize the HKDF KeyGenerator with a HKDFExpandOnlyParameterSpec, e.g.:

 // the input key:
 byte[] prk = ...;
 // the info string:
 byte[] info = ...;
 // the length of the output key:
 byte[] l = ...;
 // create a HKDF KeyGenerator for the desired hash function:
 KeyGenerator hkdf = KeyGenerator.getInstance("HKDFwithSHA256");
 // initialize the HKDF:
 HKDFExpandOnlyParameterSpec hkdfParamSpec = new HKDFExpandOnlyParameterSpec(prk, info, L);
 hkdf.init(hkdfParamSpec, null);
 // generate the key:
 SecretKey key = hkdf.generateKey(); 
 

See Also:

HKDFParameterSpec, HKDFExpandOnlyParameterSpec, HKDF.HKDFwithSHA1, HKDF.HKDFwithSHA224, HKDF.HKDFwithSHA256, HKDF.HKDFwithSHA384, HKDF.HKDFwithSHA512

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HKDF.HKDFwithSHA1 HKDF key derivation function using HmacSHA1.
static class	HKDF.HKDFwithSHA224 HKDF key derivation function using HmacSHA224.
static class	HKDF.HKDFwithSHA256 HKDF key derivation function using HmacSHA256.
static class	HKDF.HKDFwithSHA384 HKDF key derivation function using HmacSHA384.
static class	HKDF.HKDFwithSHA512 HKDF key derivation function using HmacSHA512.

Method Summary

Methods

Modifier and Type	Method and Description
javax.crypto.SecretKey	engineGenerateKey() Derives symmetric key.
void	engineInit(java.security.spec.AlgorithmParameterSpec paramSpec, java.security.SecureRandom secureRandom) Initializes this HKDF key derivation function.
void	engineInit(int int1, java.security.SecureRandom secureRandom) This method is not supported.
void	engineInit(java.security.SecureRandom secureRandom) This method is not supported.

Methods inherited from class java.lang.Object

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

Method Detail

engineGenerateKey

public javax.crypto.SecretKey engineGenerateKey()

Derives symmetric key. The algorithm name of the derived key is set to "RAW" and may be later changed by the calling application, if required:

 String algorithm = ...;
 KeyGenerator hkdf = KeyGenerator.getInstance("HKDFwithSHA256", "IAIK");
 ...
 iaik.security.cipher.SecretKey secretKey = (iaik.security.cipher.SecretKey)hkdf.generateKey();
 secretKey.setAlgorithm(algorithm);
 

Specified by:

engineGenerateKey in class javax.crypto.KeyGeneratorSpi

Returns:

the derived key

engineInit

public void engineInit(int int1,
              java.security.SecureRandom secureRandom)

This method is not supported.

Specified by:

engineInit in class javax.crypto.KeyGeneratorSpi

Throws:

java.lang.UnsupportedOperationException

engineInit

public void engineInit(java.security.SecureRandom secureRandom)

This method is not supported.

Specified by:

engineInit in class javax.crypto.KeyGeneratorSpi

Throws:

java.lang.UnsupportedOperationException

engineInit

public void engineInit(java.security.spec.AlgorithmParameterSpec paramSpec,
              java.security.SecureRandom secureRandom)
                throws java.security.InvalidAlgorithmParameterException

Initializes this HKDF key derivation function.

Specified by:

engineInit in class javax.crypto.KeyGeneratorSpi

Parameters:

paramSpec - the AlgorithmParameterSpec for initializing this KeyGenerator; must be an instance of HKDFParameterSpec or HKDFExpandOnlyParameterSpec

secureRandom - not needed, should be null

Throws:

java.security.InvalidAlgorithmParameterException