Interface HKDFParameterSpec

All Superinterfaces:

AlgorithmParameterSpec

All Known Implementing Classes:

HKDFParameterSpec.ExpandPREVIEW, HKDFParameterSpec.ExtractPREVIEW, HKDFParameterSpec.ExtractThenExpandPREVIEW

public interface HKDFParameterSpec
extends AlgorithmParameterSpec

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, Expand, or Extract-then-Expand operations of the HMAC-based Key Derivation Function (HKDF). The HKDF function is defined in RFC 5869.

In the Extract and Extract-then-Expand cases, users may call the addIKM and/or addSalt methods repeatedly (and chain these calls). This provides for use-cases where a portion of the input keying material (IKM) resides in a non-extractable SecretKey and the whole IKM cannot be provided as a single object. 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:

 // this usage depicts the initialization of an HKDF-Extract AlgorithmParameterSpec
 AlgorithmParameterSpec derivationSpec =
             HKDFParameterSpec.ofExtract()
                              .addIKM(label)
                              .addIKM(ikm)
                              .addSalt(salt).extractOnly();

 // this usage depicts the initialization of an HKDF-Expand AlgorithmParameterSpec
 AlgorithmParameterSpec derivationSpec =
             HKDFParameterSpec.expandOnly(prk, info, 32);

 // this usage depicts the initialization of an HKDF-ExtractExpand AlgorithmParameterSpec
 AlgorithmParameterSpec derivationSpec =
             HKDFParameterSpec.ofExtract()
                              .addIKM(ikm)
                              .addSalt(salt).thenExpand(info, 32);

Since:

24

External Specifications

• RFC 5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)

See Also:

• KDF^PREVIEW

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	HKDFParameterSpec.BuilderPREVIEW	Preview. This Builder builds Extract and ExtractThenExpand objects.
static final class	HKDFParameterSpec.ExpandPREVIEW	Preview. Defines the input parameters of an Expand operation as defined in RFC 5869.
static final class	HKDFParameterSpec.ExtractPREVIEW	Preview. Defines the input parameters of an Extract operation as defined in RFC 5869.
static final class	HKDFParameterSpec.ExtractThenExpandPREVIEW	Preview. Defines the input parameters of an Extract-then-Expand operation as defined in RFC 5869.

Method Summary

Static Methods

Modifier and Type	Method	Description
static HKDFParameterSpec.ExpandPREVIEW	expandOnly(SecretKey prk, byte[] info, int length)	Creates an Expand object.
static HKDFParameterSpec.BuilderPREVIEW	ofExtract()	Returns a Builder for building Extract and ExtractThenExpand objects.

Method Details

ofExtract

static HKDFParameterSpec.BuilderPREVIEW ofExtract()

Returns a Builder for building Extract and ExtractThenExpand objects.

Returns:

a new Builder

expandOnly

static HKDFParameterSpec.ExpandPREVIEW expandOnly(SecretKey prk,
 byte[] info,
 int length)

Creates an Expand object.

Implementation Note:

HKDF implementations will enforce that the length is not greater than 255 * HMAC length. Implementations will also enforce that the prk argument is at least as many bytes as the HMAC length. Implementations will also enforce that a {code null} info value is treated as zero-length byte array.

Parameters:

prk - the pseudorandom key (PRK); must not be null

info - the optional context and application specific information (may be null); the byte array is cloned to prevent subsequent modification

length - the length of the output keying material (must be greater than 0)

Returns:

an Expand object

Throws:

NullPointerException - if the prk argument is null

IllegalArgumentException - if length is not greater than 0