Interface HKDFParameterSpec

All Superinterfaces:
KDFParameterSpecPREVIEW
All Known Implementing Classes:
HKDFParameterSpec.ExpandPREVIEW, HKDFParameterSpec.ExtractPREVIEW, HKDFParameterSpec.ExtractThenExpandPREVIEW

public interface HKDFParameterSpec extends KDFParameterSpecPREVIEW
HKDFParameterSpec is a preview API of the Java platform.
Programs can only use HKDFParameterSpec when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
Parameters for the combined Extract-Only, Expand-Only, or Extract-then-Expand operations of the HMAC-based Key Derivation Function (HKDF). The HKDF function is defined in RFC 5869.

In the Extract-Only and Extract-then-Expand cases, the addIKM and addSalt methods may be called repeatedly (and chained). This provides for use-cases where a SecretKey may reside on an HSM and not be exportable. The caller may wish to provide a label (or other components) of the IKM without having access to the portion stored on the HSM. The same feature is available for salts.

The above feature is particularly useful for "labeled" HKDF Extract used in TLS 1.3 and HPKE, where the IKM consists of concatenated components, which may include both byte arrays and (possibly non-extractable) secret keys.

Examples:


 KDFParameterSpec kdfParameterSpec =
             HKDFParameterSpec.ofExtract()
                              .addIKM(ikmPart1)
                              .addIKM(ikmPart2)
                              .addSalt(salt).extractOnly();



 KDFParameterSpec kdfParameterSpec = HKDFParameterSpec.expandOnly(prk,
 info, 32);


 KDFParameterSpec kdfParameterSpec =
             HKDFParameterSpec.ofExtract()
                              .addIKM(ikm)
                              .addSalt(salt).thenExpand(info, 42);

Since:
23
  • Method Details

    • ofExtract

      Returns a builder for building Extract-Only and ExtractThenExpand objects.

      Note: one or more of the methods addIKM or addSalt should be called next, before calling build methods, such as Builder.extractOnly()

      Returns:
      a Builder to mutate
    • expandOnly

      static HKDFParameterSpec.ExpandPREVIEW expandOnly(SecretKey prk, byte[] info, int length)
      Defines the input parameters of an Expand-Only object
      Parameters:
      prk - the pseudorandom key; must not be null in the Expand-Only case
      info - the optional context and application specific information (may be null); the byte[] is copied to prevent subsequent modification
      length - the length of the output key material (must be > 0 and < 255 * HMAC length)
      Returns:
      a new Expand object
      Throws:
      NullPointerException - if prk is null
      IllegalArgumentException - if length is not > 0