at.favre.lib.crypto

Interface HFunction

All Known Implementing Classes:

HFunction.MacHFunction, HFunction.MessageDigestHFunction

public interface HFunction

The auxiliary function used to produce blocks of keying material during the execution of the one-step key-derivation method. Basically an abstraction of either MessageDigest or Mac

Options for the Auxiliary Function H:

• hash(x), where hash is an approved hash function
• HMAC-hash(salt, x), where HMAC-hash is an implementation of the HMAC algorithm
• KMAC#(salt, x, H_outputBits, S), where KMAC# is a particular implementation of either KMAC128 or KMAC256

An example on how to use a H-function

     final HFunction func = factory.createInstance();
     final int hashLength = func.getHFuncOutputBytes();
     byte[] out = new byte[hashLength];
     func.update(keyData);
     out = func.calculate()
 

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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	HFunction.MacHFunction HMAC implementation of the H function
static class	HFunction.MessageDigestHFunction Hash implementation of the H function.

Method Summary

Modifier and Type	Method and Description
byte[]	calculate() After adding the input through update(byte[]) calculate the output of the H-function
int	getHFuncOutputBytes() Formally: a positive integer that indicates the length of the output of the auxiliary function, H, that is used to derive blocks of secret keying material.
void	init(byte[] key) Optional keying of the H function.
boolean	requireInit() If the function requires a key to be provided in the init(byte[])
void	reset() Resets the function for further use.
void	update(byte[] array) Update the function with a new input that will internally added to the already available input

Method Detail

init

void init(byte[] key)

Optional keying of the H function. This is not supported with hash type functions and may throw an UnsupportedOperationException. Call this before update(byte[])

Parameters:

key - to be used; if null is passed, default_salt is used, which is in the case of HMAC a empty byte array the length of the underyling hash function (e.g. 32 bytes for SHA-256)

requireInit

boolean requireInit()

If the function requires a key to be provided in the init(byte[])

Returns:

true if user must initialize with init()

getHFuncOutputBytes

int getHFuncOutputBytes()

Formally: a positive integer that indicates the length of the output of the auxiliary function, H, that is used to derive blocks of secret keying material.

The spec describes the length in bits, but for practical reasons it will return bytes.

Practically the length of output hash/hmac/kmac function. E.g. SHA-256 or HMAC_SHA-256 will output 32 byte long block.

Returns:

output length in byte

update

void update(byte[] array)

Update the function with a new input that will internally added to the already available input

Parameters:

array - to process

calculate

byte[] calculate()

After adding the input through update(byte[]) calculate the output of the H-function

Returns:

output (usually a hash)

reset

void reset()

Resets the function for further use.