org.apache.xml.security.encryption.keys.content.derivedKey

Class HKDF

java.lang.Object

org.apache.xml.security.encryption.keys.content.derivedKey.HKDF

All Implemented Interfaces:

DerivationAlgorithm<HKDFParams>

public class HKDF
extends Object
implements DerivationAlgorithm<HKDFParams>

The implementation of the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869.

The HKDF algorithm is defined as follows:

 N = ceil(L/HashLen)
 T = T(1) | T(2) | T(3) | ... | T(N)
 OKM = first L bytes of T
 where:
 T(0) = empty string (zero length)
 T(1) = HMAC-Hash(PRK, T(0) | info | 0x01)
 T(2) = HMAC-Hash(PRK, T(1) | info | 0x02)
 T(3) = HMAC-Hash(PRK, T(2) | info | 0x03)
 ...
 

Constructor Summary

Constructors

Constructor and Description
HKDF()

Method Summary

Modifier and Type	Method and Description
byte[]	deriveKey(byte[] secret, HKDFParams params) Derive a key using the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869.
byte[]	expandKey(String jceHmacAlgorithmName, byte[] prk, byte[] info, long keyLength) The method inits Hash-MAC with given PRK (as salt) and output OKM is calculated as follows: T(0) = empty string (zero length) T(1) = HMAC-Hash(PRK, T(0) | info | 0x01) T(2) = HMAC-Hash(PRK, T(1) | info | 0x02) T(3) = HMAC-Hash(PRK, T(2) | info | 0x03) ...
byte[]	extractKey(String jceAlgorithmName, byte[] salt, byte[] secret) The method "extracts" the pseudo-random key (PRK) based on HMAC-Hash function (optional) salt value (a non-secret random value) and the shared secret/input keying material (IKM).

Methods inherited from class java.lang.Object

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

Constructor Detail

HKDF

public HKDF()

Method Detail

deriveKey

public byte[] deriveKey(byte[] secret,
                        HKDFParams params)
                 throws XMLSecurityException

Derive a key using the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869.

Specified by:

deriveKey in interface DerivationAlgorithm<HKDFParams>

Parameters:

secret - The "shared" secret to use for key derivation

params - The key derivation parameters (salt, info, key length, ...)

Returns:

The derived key of the specified length in bytes defined in the params

Throws:

IllegalArgumentException - if the parameters are missing

XMLSecurityException - if the hmac hash algorithm is not supported

extractKey

public byte[] extractKey(String jceAlgorithmName,
                         byte[] salt,
                         byte[] secret)
                  throws XMLSecurityException

The method "extracts" the pseudo-random key (PRK) based on HMAC-Hash function (optional) salt value (a non-secret random value) and the shared secret/input keying material (IKM). Calculation of the extracted key:

PRK = HMAC-Hash(salt, IKM)

Parameters:

jceAlgorithmName - the java JCE HMAC algorithm name to use for key derivation (e.g. HmacSHA256, HmacSHA384, HmacSHA512)

salt - the optional salt value (a non-secret random value);

secret - the shared secret/input keying material (IKM) to use for key derivation

Returns:

the pseudo-random key bytes

Throws:

XMLSecurityException - if the jceAlgorithmName is not supported

expandKey

public byte[] expandKey(String jceHmacAlgorithmName,
                        byte[] prk,
                        byte[] info,
                        long keyLength)
                 throws XMLSecurityException

The method inits Hash-MAC with given PRK (as salt) and output OKM is calculated as follows:

  T(0) = empty string (zero length)
  T(1) = HMAC-Hash(PRK, T(0) | info | 0x01)
  T(2) = HMAC-Hash(PRK, T(1) | info | 0x02)
  T(3) = HMAC-Hash(PRK, T(2) | info | 0x03)
  ...
  

Parameters:

jceHmacAlgorithmName - the java JCE HMAC algorithm name to use to expand the key (e.g. HmacSHA256, HmacSHA384, HmacSHA512)

prk - pseudo-random key derived from the shared secret

info - used to derive the key

keyLength - key length in bytes of the derived key

Returns:

the output keying material (OKM) size of keyLength octets

Throws:

XMLSecurityException - if the jceHmacAlgorithmName is not supported