at.favre.lib.crypto

Class SingleStepKdf

java.lang.Object

at.favre.lib.crypto.SingleStepKdf

public final class SingleStepKdf
extends Object

Single Step Key Derivation Function (KDF) as described in NIST SP 800-56Cr1 chapter 4.

Formally described as:

A family of one-step key-derivation functions is specified as follows: Function call: KDM( Z, OtherInput ).

Options for the Auxiliary Function H:

• H(x) = hash(x), where hash is an approved hash function meeting the selection requirements specified in Section 7, and the input, x, is a bit string.
• H(x) = HMAC-hash(salt, x), where HMAC-hash is an implementation of the HMAC algorithm (as defined in [FIPS 198]) employing an approved hash function, hash, that meets the selection requirements specified in Section 7. An implementation-dependent byte string, salt, whose (non-null) value may be optionally provided in OtherInput, serves as the HMAC key, and x (the input to H) is a bit string that serves as the HMAC “message” – as specified in [FIPS 198].
• H(x) = KMAC#(salt, x, H_outputBits, S), where KMAC# is a particular implementation of either KMAC128 or KMAC256 (as defined in [SP 800-185]) that meets the selection requirements specified in Section 7. An implementation-dependent byte string, salt, whose (non-null) value may be optionally provided in OtherInput, serves as the KMAC# key, and x (the input to H) is a bit string that serves as the KMAC# “message” – as specified in [SP800-185]. The parameter H_outputBits determines the bit length chosen for the output of the KMAC variant employed. The “customization string” S shall be the byte string 01001011 || 01000100 || 01000110, which represents the sequence of characters “K”, “D”, and “F” in 8-bit ASCII. (This three-byte string is denoted by “KDF” in this document.)

see https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Cr1.pdf

Method Summary

Modifier and Type	Method and Description
byte[]	derive(byte[] sharedSecretZ, int outLengthBytes) KDM - a one step key derivation function as described in NIST SP 800-56C REV.
byte[]	derive(byte[] sharedSecretZ, int outLengthBytes, byte[] fixedInfo) KDM - a one step key derivation function as described in NIST SP 800-56C REV.
byte[]	derive(byte[] sharedSecretZ, int outLengthBytes, byte[] salt, byte[] fixedInfo) KDM - a one step key derivation function as described in NIST SP 800-56C REV.
static SingleStepKdf	from(HFunctionFactory factory)
static SingleStepKdf	fromHmacSha256()
static SingleStepKdf	fromHmacSha512()
static SingleStepKdf	fromSha256()
static SingleStepKdf	fromSha512()
String	getHFunctionDescription() Get a user readable description of the used H-function (e.g.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

fromSha256

public static SingleStepKdf fromSha256()

fromSha512

public static SingleStepKdf fromSha512()

fromHmacSha256

public static SingleStepKdf fromHmacSha256()

fromHmacSha512

public static SingleStepKdf fromHmacSha512()

from

public static SingleStepKdf from(HFunctionFactory factory)

getHFunctionDescription

public String getHFunctionDescription()

Get a user readable description of the used H-function (e.g. SHA-256 or HmacSha1 or similar)

Returns:

description

derive

public byte[] derive(byte[] sharedSecretZ,
                     int outLengthBytes)

KDM - a one step key derivation function as described in NIST SP 800-56C REV. 1 Chapter 4.1.

Derives a new key from given parameters. This call omits the salt which is applicable for KDFs which use a MessageDigest as underlying H function. This call also uses a zero length byte array as fixedInfo. Using an empty fixedInfo is a special case and the caller should have specific reasons to omit it.

Parameters:

sharedSecretZ - called 'Z' in the spec: a byte string that represents the shared secret

outLengthBytes - called 'L' in the spec: a positive integer that indicates the length (in bytes) of the secret keying material to be derived (ie. how long the output will be in bytes)

Returns:

derived keying material (to use as secret key)

derive

public byte[] derive(byte[] sharedSecretZ,
                     int outLengthBytes,
                     byte[] fixedInfo)

KDM - a one step key derivation function as described in NIST SP 800-56C REV. 1 Chapter 4.1.

Derives a new key from given parameters. This call omits the salt which is applicable for KDFs which use a MessageDigest as underlying H function.

Parameters:

sharedSecretZ - called 'Z' in the spec: a byte string that represents the shared secret

outLengthBytes - called 'L' in the spec: a positive integer that indicates the length (in bytes) of the secret keying material to be derived (ie. how long the output will be in bytes)

fixedInfo - a bit string of context-specific data that is appropriate for the relying key-establishment scheme. FixedInfo may, for example, include appropriately formatted representations of the values of salt and/or L. The inclusion of additional copies of the values of salt and L in FixedInfo would ensure that each block of derived keying material is affected by all of the information conveyed in OtherInput. See [SP 800-56A] and [SP 800-56B] for more detailed recommendations concerning the format and content of FixedInfo.

Returns:

derived keying material (to use as secret key)

derive

public byte[] derive(byte[] sharedSecretZ,
                     int outLengthBytes,
                     byte[] salt,
                     byte[] fixedInfo)

KDM - a one step key derivation function as described in NIST SP 800-56C REV. 1 Chapter 4.1.

Derives a new key from given parameters.

Parameters:

sharedSecretZ - called 'Z' in the spec: a byte string that represents the shared secret

outLengthBytes - called 'L' in the spec: a positive integer that indicates the length (in bytes) of the secret keying material to be derived (ie. how long the output will be in bytes)

salt - (secret or non-secret) byte string that should be provided when HMAC h function is used, if null is passed the default_salt is used

fixedInfo - a bit string of context-specific data that is appropriate for the relying key-establishment scheme. FixedInfo may, for example, include appropriately formatted representations of the values of salt and/or L. The inclusion of additional copies of the values of salt and L in FixedInfo would ensure that each block of derived keying material is affected by all of the information conveyed in OtherInput. See [SP 800-56A] and [SP 800-56B] for more detailed recommendations concerning the format and content of FixedInfo.

Returns:

derived keying material (to use as secret key)

Throws:

IllegalArgumentException - if salt is used with message digest as H function