Modifier and Type	Class and Description
pack-priv static class	HKDF.Expander
pack-priv static class	HKDF.Extractor

Modifier and Type	Field and Description
private static HKDF	hkdfHmacSha256 Cache instances
private static HKDF	hkdfHmacSha512
private final HkdfMacFactory	macFactory

Access	Constructor and Description
private	HKDF(HkdfMacFactory macFactory)

Method Summary

Modifier and Type	Method and Description
public byte[]	Returns: new byte array of output keying material (OKM) expand(byte[] a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step) pseudoRandomKey, byte[] optional context and application specific information; may be null info, int length of output keying material in bytes 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.
public byte[]	Returns: new byte array of output keying material (OKM) expand(SecretKey a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step) pseudoRandomKey, byte[] optional context and application specific information; may be null info, int length of output keying material in bytes outLengthBytes) Use this if you require `SecretKey` types by your security framework.
public byte[]	Returns: a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand extract(byte[] 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. salt, byte[] data to be extracted (IKM) inputKeyingMaterial) 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.
public byte[]	Returns: a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand extract(SecretKey optional salt value (a non-secret random value) (can be null) salt, byte[] data to be extracted (IKM) inputKeyingMaterial) Use this if you require `SecretKey` types by your security framework.
public byte[]	Returns: new byte array of output keying material (OKM) extractAndExpand(byte[] optional salt value (a non-secret random value); saltExtract, byte[] data to be extracted (IKM) inputKeyingMaterial, byte[] optional context and application specific information; may be null infoExpand, int length of output keying material in bytes outLengthByte) Convenience method for extract & expand in a single method
public byte[]	Returns: new byte array of output keying material (OKM) extractAndExpand(SecretKey optional salt value (a non-secret random value); saltExtract, byte[] data to be extracted (IKM) inputKeyingMaterial, byte[] optional context and application specific information; may be null infoExpand, int length of output keying material in bytes outLengthByte) Convenience method for extract & expand in a single method
public static HKDF	Returns: a new instance of HKDF from(HkdfMacFactory used for HKDF macFactory) Create a new HKDF instance for given macFactory.
public static HKDF	Returns: HKDF instance fromHmacSha256() Return a shared instance using HMAC with Sha256.
public static HKDF	Returns: HKDF instance fromHmacSha512() Return a shared instance using HMAC with Sha512.
pack-priv HkdfMacFactory	Returns: factory getMacFactory() Get the used mac factory

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

hkdfHmacSha256	back to summary
private static HKDF hkdfHmacSha256 Cache instances

hkdfHmacSha512	back to summary
private static HKDF hkdfHmacSha512

macFactory	back to summary
private final HkdfMacFactory macFactory

Constructor Detail

HKDF	back to summary
private HKDF(HkdfMacFactory macFactory)

Method Detail

expand	back to summary
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:byte[] a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step) info:byte[] optional context and application specific information; may be null outLengthBytes:int length of output keying material in bytes Returns:byte[] new byte array of output keying material (OKM) See Also RFC 5869 Section 2.3

expand

back to summary

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:byte[]: a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step)
info:byte[]: optional context and application specific information; may be null
outLengthBytes:int: length of output keying material in bytes

Returns:byte[]

new byte array of output keying material (OKM)

See Also

RFC 5869 Section 2.3

expand back to summary

expand	back to summary
public byte[] expand(SecretKey pseudoRandomKey, byte[] info, int outLengthBytes) Use this if you require `SecretKey` types by your security framework. See also `HkdfMacFactory#createSecretKey(byte[])`. See `expand(byte[], byte[], int)` for description. Parameters pseudoRandomKey:SecretKey a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step) info:byte[] optional context and application specific information; may be null outLengthBytes:int length of output keying material in bytes Returns:byte[] new byte array of output keying material (OKM)

public byte[] expand(SecretKey pseudoRandomKey, byte[] info, int outLengthBytes)

Use this if you require SecretKey types by your security framework. See also HkdfMacFactory#createSecretKey(byte[]).

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

Parameters

pseudoRandomKey:SecretKey: a pseudo random key of at least hmac hash length in bytes (usually, the output from the extract step)
info:byte[]: optional context and application specific information; may be null
outLengthBytes:int: length of output keying material in bytes

Returns:byte[]

new byte array of output keying material (OKM)

extract	back to summary
public byte[] extract(byte[] salt, byte[] inputKeyingMaterial) 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:byte[] 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. inputKeyingMaterial:byte[] data to be extracted (IKM) Returns:byte[] a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand See Also RFC 5869 Section 2.2

extract

back to summary

public byte[] extract(byte[] salt, byte[] inputKeyingMaterial)

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:byte[]: 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.
inputKeyingMaterial:byte[]: data to be extracted (IKM)

Returns:byte[]

a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand

See Also

RFC 5869 Section 2.2

extract back to summary

extract	back to summary
public byte[] extract(SecretKey salt, byte[] inputKeyingMaterial) Use this if you require `SecretKey` types by your security framework. See also `HkdfMacFactory#createSecretKey(byte[])`. See `extract(byte[], byte[])` for description. Parameters salt:SecretKey optional salt value (a non-secret random value) (can be null) inputKeyingMaterial:byte[] data to be extracted (IKM) Returns:byte[] a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand

public byte[] extract(SecretKey salt, byte[] inputKeyingMaterial)

Use this if you require SecretKey types by your security framework. See also HkdfMacFactory#createSecretKey(byte[]).

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

Parameters

salt:SecretKey: optional salt value (a non-secret random value) (can be null)
inputKeyingMaterial:byte[]: data to be extracted (IKM)

Returns:byte[]

a new byte array pseudo random key (of hash length in bytes) (PRK) which can be used to expand

extractAndExpand	back to summary
public byte[] extractAndExpand(byte[] saltExtract, byte[] inputKeyingMaterial, byte[] infoExpand, int outLengthByte) Convenience method for extract & expand in a single method Parameters saltExtract:byte[] optional salt value (a non-secret random value); inputKeyingMaterial:byte[] data to be extracted (IKM) infoExpand:byte[] optional context and application specific information; may be null outLengthByte:int length of output keying material in bytes Returns:byte[] new byte array of output keying material (OKM)

extractAndExpand

back to summary

public byte[] extractAndExpand(byte[] saltExtract, byte[] inputKeyingMaterial, byte[] infoExpand, int outLengthByte)

Convenience method for extract & expand in a single method

Parameters

saltExtract:byte[]: optional salt value (a non-secret random value);
inputKeyingMaterial:byte[]: data to be extracted (IKM)
infoExpand:byte[]: optional context and application specific information; may be null
outLengthByte:int: length of output keying material in bytes

Returns:byte[]

new byte array of output keying material (OKM)

extractAndExpand	back to summary
public byte[] extractAndExpand(SecretKey saltExtract, byte[] inputKeyingMaterial, byte[] infoExpand, int outLengthByte) Convenience method for extract & expand in a single method Parameters saltExtract:SecretKey optional salt value (a non-secret random value); inputKeyingMaterial:byte[] data to be extracted (IKM) infoExpand:byte[] optional context and application specific information; may be null outLengthByte:int length of output keying material in bytes Returns:byte[] new byte array of output keying material (OKM)

extractAndExpand

back to summary

public byte[] extractAndExpand(SecretKey saltExtract, byte[] inputKeyingMaterial, byte[] infoExpand, int outLengthByte)

Convenience method for extract & expand in a single method

Parameters

saltExtract:SecretKey: optional salt value (a non-secret random value);
inputKeyingMaterial:byte[]: data to be extracted (IKM)
infoExpand:byte[]: optional context and application specific information; may be null
outLengthByte:int: length of output keying material in bytes

Returns:byte[]

new byte array of output keying material (OKM)

from	back to summary
public static HKDF from(HkdfMacFactory macFactory) Create a new HKDF instance for given macFactory. Parameters macFactory:HkdfMacFactory used for HKDF Returns:HKDF a new instance of HKDF

from

back to summary

public static HKDF from(HkdfMacFactory macFactory)

Create a new HKDF instance for given macFactory.

Parameters

macFactory:HkdfMacFactory: used for HKDF

Returns:HKDF

a new instance of HKDF

fromHmacSha256	back to summary
public static HKDF fromHmacSha256() Return a shared instance using HMAC with Sha256. Even though shared, this instance is thread-safe. Returns:HKDF HKDF instance

fromHmacSha256

back to summary

public static HKDF fromHmacSha256()

Return a shared instance using HMAC with Sha256. Even though shared, this instance is thread-safe.

Returns:HKDF: HKDF instance

fromHmacSha512	back to summary
public static HKDF fromHmacSha512() Return a shared instance using HMAC with Sha512. Even though shared, this instance is thread-safe. Returns:HKDF HKDF instance

fromHmacSha512

back to summary

public static HKDF fromHmacSha512()

Return a shared instance using HMAC with Sha512. Even though shared, this instance is thread-safe.

Returns:HKDF: HKDF instance

getMacFactory	back to summary
pack-priv HkdfMacFactory getMacFactory() Get the used mac factory Returns:HkdfMacFactory factory

getMacFactory

back to summary

pack-priv HkdfMacFactory getMacFactory()

Get the used mac factory

Returns:HkdfMacFactory: factory

at.favre.lib.crypto back to summary

pack-priv final Class HKDF.Expander

Class Inheritance

extends Object

java.lang.Object
at.favre.lib.crypto.HKDF.Expander

Field Summary

Modifier and Type	Field and Description
private final HkdfMacFactory	macFactory

Constructor Summary

Access	Constructor and Description
pack-priv	Expander(HkdfMacFactory macFactory)

Method Summary

Modifier and Type	Method and Description
pack-priv byte[]	Returns: new byte array of output keying material (OKM) execute(SecretKey a pseudorandom key of at least hmac hash length in bytes (usually, the output from the extract step) pseudoRandomKey, byte[] optional context and application specific information; may be null info, int length of output keying material in bytes (must be <= 255 * mac hash length) outLengthBytes) Step 2 of RFC 5869.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

macFactory	back to summary
private final HkdfMacFactory macFactory

Constructor Detail

Expander	back to summary
pack-priv Expander(HkdfMacFactory macFactory)

Method Detail

execute	back to summary
pack-priv byte[] execute(SecretKey pseudoRandomKey, byte[] info, int outLengthBytes) Step 2 of RFC 5869. Parameters pseudoRandomKey:SecretKey a pseudorandom key of at least hmac hash length in bytes (usually, the output from the extract step) info:byte[] optional context and application specific information; may be null outLengthBytes:int length of output keying material in bytes (must be <= 255 * mac hash length) Returns:byte[] new byte array of output keying material (OKM)

execute

back to summary

pack-priv byte[] execute(SecretKey pseudoRandomKey, byte[] info, int outLengthBytes)

Step 2 of RFC 5869.

Parameters

pseudoRandomKey:SecretKey: a pseudorandom key of at least hmac hash length in bytes (usually, the output from the extract step)
info:byte[]: optional context and application specific information; may be null
outLengthBytes:int: length of output keying material in bytes (must be <= 255 * mac hash length)

Returns:byte[]

new byte array of output keying material (OKM)

at.favre.lib.crypto back to summary

pack-priv final Class HKDF.Extractor

Class Inheritance

extends Object

java.lang.Object
at.favre.lib.crypto.HKDF.Extractor

Field Summary

Modifier and Type	Field and Description
private final HkdfMacFactory	macFactory

Constructor Summary

Access	Constructor and Description
pack-priv	Extractor(HkdfMacFactory macFactory)

Method Summary

Modifier and Type	Method and Description
pack-priv byte[]	Returns: a new byte array pseudorandom key (of hash length in bytes) (PRK) which can be used to expand execute(SecretKey optional salt value (a non-secret random value); if not provided, it is set to an array of hash length of zeros. salt, byte[] data to be extracted (IKM) inputKeyingMaterial) Step 1 of RFC 5869

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

macFactory	back to summary
private final HkdfMacFactory macFactory

Constructor Detail

Extractor	back to summary
pack-priv Extractor(HkdfMacFactory macFactory)

Method Detail

execute	back to summary
pack-priv byte[] execute(SecretKey salt, byte[] inputKeyingMaterial) Step 1 of RFC 5869 Parameters salt:SecretKey optional salt value (a non-secret random value); if not provided, it is set to an array of hash length of zeros. inputKeyingMaterial:byte[] data to be extracted (IKM) Returns:byte[] a new byte array pseudorandom key (of hash length in bytes) (PRK) which can be used to expand

execute

back to summary

pack-priv byte[] execute(SecretKey salt, byte[] inputKeyingMaterial)

Step 1 of RFC 5869

Parameters

salt:SecretKey: optional salt value (a non-secret random value); if not provided, it is set to an array of hash length of zeros.
inputKeyingMaterial:byte[]: data to be extracted (IKM)

Returns:byte[]

a new byte array pseudorandom key (of hash length in bytes) (PRK) which can be used to expand

public final Class HKDF

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class HKDF.Expander

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class HKDF.Extractor

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail