APIdia Launch Partner
Top Description Inners Methods
javax.crypto.spec

public Interface HKDFParameterSpec

extends AlgorithmParameterSpec
Known Direct Implementers
javax.crypto.spec.HKDFParameterSpec.Extract, javax.crypto.spec.HKDFParameterSpec.Expand, javax.crypto.spec.HKDFParameterSpec.ExtractThenExpand
Imports
javax.crypto.SecretKey, java.security.spec.AlgorithmParameterSpec, java.util.ArrayList, .List, .Objects
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-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-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); 
// this usage depicts the initialization of an HKDF-ExtractExpand
// AlgorithmParameterSpec
AlgorithmParameterSpec derivationSpec =
            HKDFParameterSpec.ofExtract()
                             .addIKM(ikm)
                             .addSalt(salt).thenExpand(info, 32);
Since
25
External Specification
https://www.rfc-editor.org/info/rfc5869
See Also
javax.crypto.KDF

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
HKDFParameterSpec.Builder

This Builder builds Extract and ExtractThenExpand objects.

public static class
HKDFParameterSpec.Expand

Defines the input parameters of an Expand operation as defined in RFC 5869.

public static class
HKDFParameterSpec.Extract

Defines the input parameters of an Extract operation as defined in RFC 5869.

public static class
HKDFParameterSpec.ExtractThenExpand

Defines the input parameters of an Extract-then-Expand operation as defined in RFC 5869.

Method Summary

Modifier and TypeMethod and Description
public static HKDFParameterSpec.Expand

Returns:

an Expand object
expandOnly(SecretKey
the pseudorandom key (PRK); must not be null
prk, byte[]
the optional context and application specific information (may be null); the byte array is cloned to prevent subsequent modification
info, int
the length of the output keying material (must be greater than 0)
length)

Creates an Expand object.

public static HKDFParameterSpec.Builder

Returns:

a new Builder
ofExtract()

Returns a Builder for building Extract and ExtractThenExpand objects.

Method Detail

expandOnlyback to summary
public static HKDFParameterSpec.Expand 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 null info value is treated as zero-length byte array.

Parameters
prk:SecretKey

the pseudorandom key (PRK); must not be null

info:byte[]

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

length:int

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

Returns:HKDFParameterSpec.Expand

an Expand object

Exceptions
NullPointerException:
if the prk argument is null
IllegalArgumentException:
if length is not greater than 0
ofExtractback to summary
public static HKDFParameterSpec.Builder ofExtract()

Returns a Builder for building Extract and ExtractThenExpand objects.

Returns:HKDFParameterSpec.Builder

a new Builder

javax.crypto.spec back to summary

public final Class HKDFParameterSpec.Builder

extends Object
Class Inheritance
This Builder builds Extract and ExtractThenExpand objects.

The Builder is initialized via the ofExtract method of HKDFParameterSpec. As stated in the class description, addIKM and/or addSalt may be called as needed. Finally, an object is "built" by calling either extractOnly or thenExpand for Extract and ExtractThenExpand use-cases respectively. Note that the Builder is not thread-safe.

Field Summary

Modifier and TypeField and Description
private List<SecretKey>
ikms

private List<SecretKey>
salts

Constructor Summary

AccessConstructor and Description
private
Builder()

Method Summary

Modifier and TypeMethod and Description
public HKDFParameterSpec.Builder

Returns:

this builder
addIKM(SecretKey
the input keying material (IKM) value
ikm)

Adds input keying material (IKM) to the builder.

public HKDFParameterSpec.Builder

Returns:

this builder
addIKM(byte[]
the input keying material (IKM) value; the ikm byte array will be converted to a SecretKeySpec, which means that the byte array will be cloned inside the SecretKeySpec constructor
ikm)

Adds input keying material (IKM) to the builder.

public HKDFParameterSpec.Builder

Returns:

this builder
addSalt(SecretKey
the salt value
salt)

Adds a salt to the builder.

public HKDFParameterSpec.Builder

Returns:

this builder
addSalt(byte[]
the salt value; the salt byte array will be converted to a SecretKeySpec, which means that the byte array will be cloned inside the SecretKeySpec constructor
salt)

Adds a salt to the builder.

public HKDFParameterSpec.Extract

Returns:

an immutable Extract object
extractOnly()

Builds an Extract object from the current state of the Builder.

public HKDFParameterSpec.ExtractThenExpand

Returns:

an immutable ExtractThenExpand object
thenExpand(byte[]
the optional context and application specific information (may be null); the byte array is cloned to prevent subsequent modification
info, int
the length of the output keying material (must be greater than 0)
length)

Builds an ExtractThenExpand object from the current state of the Builder.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ikmsback to summary
private List<SecretKey> ikms
saltsback to summary
private List<SecretKey> salts

Constructor Detail

Builderback to summary
private Builder()

Method Detail

addIKMback to summary
public HKDFParameterSpec.Builder addIKM(SecretKey ikm)

Adds input keying material (IKM) to the builder.

Users may call addIKM multiple times when the input keying material value is to be assembled piece-meal or if part of the IKM is to be supplied by a hardware crypto device. The ikms() method of the Extract or ExtractThenExpand object that is subsequently built returns the assembled input keying material as a list of SecretKey objects.

Parameters
ikm:SecretKey

the input keying material (IKM) value

Returns:HKDFParameterSpec.Builder

this builder

Exceptions
NullPointerException:
if the ikm argument is null
addIKMback to summary
public HKDFParameterSpec.Builder addIKM(byte[] ikm)

Adds input keying material (IKM) to the builder. Note that an ikm byte array of length zero will be discarded.

Users may call addIKM multiple times when the input keying material value is to be assembled piece-meal or if part of the IKM is to be supplied by a hardware crypto device. The ikms() method of the Extract or ExtractThenExpand object that is subsequently built returns the assembled input keying material as a list of SecretKey objects.

Parameters
ikm:byte[]

the input keying material (IKM) value; the ikm byte array will be converted to a SecretKeySpec, which means that the byte array will be cloned inside the SecretKeySpec constructor

Returns:HKDFParameterSpec.Builder

this builder

Exceptions
NullPointerException:
if the ikm argument is null
addSaltback to summary
public HKDFParameterSpec.Builder addSalt(SecretKey salt)

Adds a salt to the builder.

Users may call addSalt multiple times when the salt value is to be assembled piece-meal or if part of the salt is to be supplied by a hardware crypto device. The salts() method of the Extract or ExtractThenExpand object that is subsequently built returns the assembled salt as a list of SecretKey objects.

Parameters
salt:SecretKey

the salt value

Returns:HKDFParameterSpec.Builder

this builder

Exceptions
NullPointerException:
if the salt is null
addSaltback to summary
public HKDFParameterSpec.Builder addSalt(byte[] salt)

Adds a salt to the builder. Note that a salt byte array of length zero will be discarded.

Users may call addSalt multiple times when the salt value is to be assembled piece-meal or if part of the salt is to be supplied by a hardware crypto device. The salts() method of the Extract or ExtractThenExpand object that is subsequently built returns the assembled salt as a list of SecretKey objects.

Parameters
salt:byte[]

the salt value; the salt byte array will be converted to a SecretKeySpec, which means that the byte array will be cloned inside the SecretKeySpec constructor

Returns:HKDFParameterSpec.Builder

this builder

Exceptions
NullPointerException:
if the salt is null
extractOnlyback to summary
public HKDFParameterSpec.Extract extractOnly()

Builds an Extract object from the current state of the Builder.

Returns:HKDFParameterSpec.Extract

an immutable Extract object

thenExpandback to summary
public HKDFParameterSpec.ExtractThenExpand thenExpand(byte[] info, int length)

Builds an ExtractThenExpand object from the current state of the Builder.

Implementation Note

HKDF implementations will enforce that the length is not greater than 255 * HMAC length. HKDF implementations will also enforce that a null info value is treated as zero-length byte array.

Parameters
info:byte[]

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

length:int

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

Returns:HKDFParameterSpec.ExtractThenExpand

an immutable ExtractThenExpand object

Exceptions
IllegalArgumentException:
if length is not greater than 0
javax.crypto.spec back to summary

public final Class HKDFParameterSpec.Expand

extends Object
implements HKDFParameterSpec
Class Inheritance
All Implemented Interfaces
javax.crypto.spec.HKDFParameterSpec, java.security.spec.AlgorithmParameterSpec
Defines the input parameters of an Expand operation as defined in RFC 5869.

Field Summary

Modifier and TypeField and Description
private final byte[]
info

private final int
length

private final SecretKey
prk

Constructor Summary

AccessConstructor and Description
private
Expand(SecretKey
the pseudorandom key (PRK); in the case of ExtractThenExpand, the prk argument may be null since the output of extract phase is used
prk, byte[]
the optional context and application specific information (may be null); the byte array is cloned to prevent subsequent modification
info, int
the length of the output keying material
length)

Constructor that may be used to initialize an Expand object

Method Summary

Modifier and TypeMethod and Description
public byte[]

Returns:

a clone of the optional context and application specific information, or null if not specified
info()

Returns the optional context and application specific information.

public int

Returns:

the length of the output keying material
length()

Returns the length of the output keying material.

public SecretKey

Returns:

the pseudorandom key
prk()

Returns the pseudorandom key (PRK).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

infoback to summary
private final byte[] info
lengthback to summary
private final int length
prkback to summary
private final SecretKey prk

Constructor Detail

Expandback to summary
private Expand(SecretKey prk, byte[] info, int length)

Constructor that may be used to initialize an Expand object

Parameters
prk:SecretKey

the pseudorandom key (PRK); in the case of ExtractThenExpand, the prk argument may be null since the output of extract phase is used

info:byte[]

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

length:int

the length of the output keying material

Exceptions
IllegalArgumentException:
if length not greater than 0

Method Detail

infoback to summary
public byte[] info()

Returns the optional context and application specific information.

Returns:byte[]

a clone of the optional context and application specific information, or null if not specified

lengthback to summary
public int length()

Returns the length of the output keying material.

Returns:int

the length of the output keying material

prkback to summary
public SecretKey prk()

Returns the pseudorandom key (PRK).

Returns:SecretKey

the pseudorandom key

javax.crypto.spec back to summary

public final Class HKDFParameterSpec.Extract

extends Object
implements HKDFParameterSpec
Class Inheritance
All Implemented Interfaces
javax.crypto.spec.HKDFParameterSpec, java.security.spec.AlgorithmParameterSpec
Defines the input parameters of an Extract operation as defined in RFC 5869.

Field Summary

Modifier and TypeField and Description
private final List<SecretKey>
ikms

private final List<SecretKey>
salts

Constructor Summary

AccessConstructor and Description
private
Extract(List<SecretKey> ikms, List<SecretKey> salts)

Method Summary

Modifier and TypeMethod and Description
public List<SecretKey>

Returns:

the unmodifiable List of input keying material values
ikms()

Returns an unmodifiable List of input keying material values in the order they were added.

public List<SecretKey>

Returns:

the unmodifiable List of salt values
salts()

Returns an unmodifiable List of salt values in the order they were added.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ikmsback to summary
private final List<SecretKey> ikms
saltsback to summary
private final List<SecretKey> salts

Constructor Detail

Extractback to summary
private Extract(List<SecretKey> ikms, List<SecretKey> salts)

Method Detail

ikmsback to summary
public List<SecretKey> ikms()

Returns an unmodifiable List of input keying material values in the order they were added. Returns an empty list if there are no input keying material values.

Input keying material values added by Builder#addIKM(byte[]) are converted to a SecretKeySpec object. Empty arrays are discarded.

Implementation Note

An HKDF implementation should concatenate the input keying materials into a single value to be used in HKDF-Extract.

Returns:List<SecretKey>

the unmodifiable List of input keying material values

saltsback to summary
public List<SecretKey> salts()

Returns an unmodifiable List of salt values in the order they were added. Returns an empty list if there are no salt values.

Salt values added by Builder#addSalt(byte[]) are converted to a SecretKeySpec object. Empty arrays are discarded.

Implementation Note

An HKDF implementation should concatenate the salts into a single value to be used in HKDF-Extract.

Returns:List<SecretKey>

the unmodifiable List of salt values

javax.crypto.spec back to summary

public final Class HKDFParameterSpec.ExtractThenExpand

extends Object
implements HKDFParameterSpec
Class Inheritance
All Implemented Interfaces
javax.crypto.spec.HKDFParameterSpec, java.security.spec.AlgorithmParameterSpec
Defines the input parameters of an Extract-then-Expand operation as defined in RFC 5869.

Field Summary

Modifier and TypeField and Description
private final HKDFParameterSpec.Expand
exp

private final HKDFParameterSpec.Extract
ext

Constructor Summary

AccessConstructor and Description
private
ExtractThenExpand(HKDFParameterSpec.Extract
a pre-generated Extract
ext, byte[]
the optional context and application specific information (may be null); the byte array is cloned to prevent subsequent modification
info, int
the length of the output keying material
length)

Constructor that may be used to initialize an ExtractThenExpand object

Method Summary

Modifier and TypeMethod and Description
public List<SecretKey>

Returns:

the unmodifiable List of input keying material values
ikms()

Returns an unmodifiable List of input keying material values in the order they were added.

public byte[]

Returns:

a clone of the optional context and application specific information, or null if not specified
info()

Returns the optional context and application specific information.

public int

Returns:

the length of the output keying material
length()

Returns the length of the output keying material.

public List<SecretKey>

Returns:

the unmodifiable List of salt values
salts()

Returns an unmodifiable List of salt values in the order they were added.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

expback to summary
private final HKDFParameterSpec.Expand exp
extback to summary
private final HKDFParameterSpec.Extract ext

Constructor Detail

ExtractThenExpandback to summary
private ExtractThenExpand(HKDFParameterSpec.Extract ext, byte[] info, int length)

Constructor that may be used to initialize an ExtractThenExpand object

Parameters
ext:HKDFParameterSpec.Extract

a pre-generated Extract

info:byte[]

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

length:int

the length of the output keying material

Exceptions
IllegalArgumentException:
if length is not greater than 0

Method Detail

ikmsback to summary
public List<SecretKey> ikms()

Returns an unmodifiable List of input keying material values in the order they were added. Returns an empty list if there are no input keying material values.

Input keying material values added by Builder#addIKM(byte[]) are converted to a SecretKeySpec object. Empty arrays are discarded.

Implementation Note

An HKDF implementation should concatenate the input keying materials into a single value to be used in the HKDF-Extract phase.

Returns:List<SecretKey>

the unmodifiable List of input keying material values

infoback to summary
public byte[] info()

Returns the optional context and application specific information.

Returns:byte[]

a clone of the optional context and application specific information, or null if not specified

lengthback to summary
public int length()

Returns the length of the output keying material.

Returns:int

the length of the output keying material

saltsback to summary
public List<SecretKey> salts()

Returns an unmodifiable List of salt values in the order they were added. Returns an empty list if there are no salt values.

Salt values added by Builder#addSalt(byte[]) are converted to a SecretKeySpec object. Empty arrays are discarded.

Implementation Note

An HKDF implementation should concatenate the salts into a single value to be used in the HKDF-Extract phase.

Returns:List<SecretKey>

the unmodifiable List of salt values