Module seppiko.commons.utils
Package org.seppiko.commons.utils.crypto

Class HKDF

java.lang.Object
org.seppiko.commons.utils.crypto.HKDF
public class HKDF extends Object
A standards-compliant implementation of RFC 5869 for HMAC-based Key Derivation Function.

HKDF follows the "extract-then-expand" paradigm, where the KDF logically consists of two modules. The first stage takes the input keying material and "extracts" from it a fixed-length pseudorandom key K. The second stage "expands" the key K into several additional pseudorandom keys (the output of the KDF).

HKDF was first described by Hugo Krawczyk.
Author:
Leonard Woo
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    expand(byte[] pseudoRandomKey, byte[] info, int outLengthBytes)
    Step 2 of RFC 5869 (Section 2.3)
    byte[]
    expand(SecretKey pseudoRandomKey, byte[] info, int outLengthBytes)
    Use this if you require SecretKey types by your security framework.
    byte[]
    extract(byte[] salt, byte[] ikm)
    Step 1 of RFC 5869 (Section 2.2)
    byte[]
    extract(SecretKey salt, byte[] ikm)
    Use this if you require SecretKey types by your security framework.
    static HKDF
    from(String algorithm)
    Create a new HKDF instance for given macFactory.
    static HKDF
    from(String algorithm, Provider provider)
    Create a new HKDF instance for given macFactory.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • from

      public static HKDF from(String algorithm)
      Create a new HKDF instance for given macFactory.
      Parameters:
      algorithm - used algorithm for HKDF.
      Returns:
      a new instance of HKDF.

    • from

      public static HKDF from(String algorithm, Provider provider)
      Create a new HKDF instance for given macFactory.
      Parameters:
      algorithm - used algorithm for HKDF.
      provider - used provider for HKDF.
      Returns:
      a new instance of HKDF.

    • extract

      public byte[] extract(byte[] salt, byte[] ikm)
      Step 1 of RFC 5869 (Section 2.2)

      The first stage takes the input keying material and "extracts" from it a fixed-length pseudorandom key K. The goal of the "extract" stage is to "concentrate" and provide a more uniformly unbiased and higher entropy but smaller output. This is done by utilising the diffusion properties of cryptographic MACs.

      About Salts (from RFC 5869):

      HKDF is defined to operate with and without random salt. This is done to accommodate applications where a salt value is not available. We stress, however, that the use of salt adds significantly to the strength of HKDF, ensuring independence between different uses of the hash function, supporting "source-independent" extraction, and strengthening the analytical results that back the HKDF design.
      Parameters:
      salt - optional salt value (a non-secret random value) (can be null) if not provided, it is set to an array of hash length of zeros.
      ikm - data to be extracted (Input Keying Material)
      Returns:
      a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand
      See Also:

    • extract

      public byte[] extract(SecretKey salt, byte[] ikm)
      Use this if you require SecretKey types by your security framework.

      See extract(byte[], byte[]) for description.

      Parameters:
      salt - optional salt value (a non-secret random value) (can be null)
      ikm - data to be extracted (Input Keying Material)
      Returns:
      a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand

    • expand

      public byte[] expand(byte[] pseudoRandomKey, byte[] info, int outLengthBytes)
      Step 2 of RFC 5869 (Section 2.3)

      To "expand" the generated output of an already reasonably random input such as an existing shared key into a larger cryptographically independent output, thereby producing multiple keys deterministically from that initial shared key, so that the same process may produce those same secret keys safely on multiple devices, as long as the same inputs are used.

      About Info (from RFC 5869):

      While the 'info' value is optional in the definition of HKDF, it is often of great importance in applications. Its main objective is to bind the derived key material to application- and context-specific information. For example, 'info' may contain a protocol number, algorithm identifiers, user identities, etc. In particular, it may prevent the derivation of the same keying material for different contexts (when the same input key material (IKM) is used in such different contexts).
      Parameters:
      pseudoRandomKey - a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step)
      info - optional context and application specific information; may be null
      outLengthBytes - length of output keying material in bytes
      Returns:
      new byte array of output keying material (OKM)
      See Also:

    • expand

      public byte[] expand(SecretKey pseudoRandomKey, byte[] info, int outLengthBytes)
      Use this if you require SecretKey types by your security framework.

      See expand(byte[], byte[], int) for description.

      Parameters:
      pseudoRandomKey - a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step)
      info - optional context and application specific information; may be null
      outLengthBytes - length of output keying material in bytes
      Returns:
      new byte array of output keying material (OKM)