Module org.apache.santuario.xmlsec
Package org.apache.xml.security.encryption.keys.content.derivedKey

Class 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

      All Methods Instance Methods Concrete Methods 
      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).

    • 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