Interface HKDFParameterSpec
- All Superinterfaces:
AlgorithmParameterSpec
- All Known Implementing Classes:
HKDFParameterSpec.ExpandPREVIEW,HKDFParameterSpec.ExtractPREVIEW,HKDFParameterSpec.ExtractThenExpandPREVIEW
HKDFParameterSpec is a preview API of the Java platform.
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
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic final classPreview.ThisBuilderbuildsExtractandExtractThenExpandobjects.static final classPreview.Defines the input parameters of an Expand operation as defined in RFC 5869.static final classPreview.Defines the input parameters of an Extract operation as defined in RFC 5869.static final classPreview.Defines the input parameters of an Extract-then-Expand operation as defined in RFC 5869. -
Method Summary
Static MethodsModifier and TypeMethodDescriptionexpandOnly(SecretKey prk, byte[] info, int length) Creates anExpandobject.Returns aBuilderfor buildingExtractandExtractThenExpandobjects.
-
Method Details
-
ofExtract
Returns aBuilderfor buildingExtractandExtractThenExpandobjects.- Returns:
- a new
Builder
-
expandOnly
Creates anExpandobject.- 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 benullinfo- the optional context and application specific information (may benull); the byte array is cloned to prevent subsequent modificationlength- the length of the output keying material (must be greater than 0)- Returns:
- an
Expandobject - Throws:
NullPointerException- if theprkargument isnullIllegalArgumentException- iflengthis not greater than 0
-
HKDFParameterSpecwhen preview features are enabled.