Module org.apache.santuario.xmlsec
Package 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
    Description
    HKDF()
     

  • Method Summary

    Modifier and Type
    Method
    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:
    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 Details

    • HKDF

      public HKDF()

  • Method Details

    • 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