iaik.security.kdf

Class HashBasedGenerationFunction

java.lang.Object

iaik.security.kdf.HashBasedGenerationFunction

All Implemented Interfaces:

java.lang.Cloneable

public class HashBasedGenerationFunction
extends java.lang.Object
implements java.lang.Cloneable

This is a helper class (and therefore shall not be used standalone by an application) for engines that produce an arbitrary long bit string by concatenating outputs of cryptographic hash functions in a specific way. This includes KDF1, KDF2 KDF3, and MGF1

All of the above classes use a hash function (donated as HASH), a counter X, some secret Z, and some additional Info Y. This class produces bit strings in multiple configurable ways, depending on the need.

• HASH - may be any MessageDigest registered
• X - initial value of counter
• Order of inputs - in which order the implementation feeds the values to the hash function

To convert the counter to a uniform string representation, we use the "Integer To Octet String Primitive" function I2OSP, which e.g., defined in ANSI X9.44–2007. In the

Using KDF2 as an example, the class computes the output string T in the following way (T is the empty string at start):

     X := 1
     repeat until T.length >= desired length
          T := T || HASH(Z||I2OSP(X, 4)||Y)
          X := X + 1
 

Constructor Summary

Constructors

Constructor and Description
HashBasedGenerationFunction(AlgorithmID hashAlgorithm, int counterOffset) Initializes the class with the provided hash algorithm and a specific starting value.
HashBasedGenerationFunction(AlgorithmID hashAlgorithm, int counterOffset, byte[] otherInfo) Initialises the class with the provided hash algorithm, a specific starting value, and some additional info Y.
HashBasedGenerationFunction(AlgorithmID hashAlgorithm, int counterOffset, byte[] otherInfo, boolean counterFirst) Initialises the class with the provided hash algorithm, a specific starting value, some additional info Y, and the position of the counter in the digest computation.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	clone()
void	engineReset() Resets the intern MessageDigest instance.
void	generateOctets(byte[] seed, int seedOff, int seedLen, int octetsLen, byte[] dst, int dstOff) Generates the bit string according to the initialisation.
AlgorithmID	getHashAlgorithm() Returns the AlgorithmID of the used hash algorithm.
void	setHashAlgorithm(AlgorithmID hashAlgorithm) Sets the AlgorithmID of the hash algorithm which the implementation uses to generate the bit string.
void	setHashEngine() Sets/resets the hash engine.
void	setHashEngine(java.security.MessageDigest messageDigest) Ignores the provided AlgorithmID and directly sets the MessageDigest instance that generateOctets(byte[], int, int, int, byte[], int) uses to generate the output string.

Methods inherited from class java.lang.Object

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

Constructor Detail

HashBasedGenerationFunction

public HashBasedGenerationFunction(AlgorithmID hashAlgorithm,
                           int counterOffset)

Initializes the class with the provided hash algorithm and a specific starting value. The implementation will perform the computation in the following way:

     X := counterOffset
     repeat until T.length >= desired length
          T := T || HASH(Z||I2OSP(X, 4))
          X := X + 1
 

whereas HASH will be an instance of the requested hashAlgorithm.

Parameters:

hashAlgorithm - the algorithm id of some hash function

counterOffset - the initial value if the counter

HashBasedGenerationFunction

public HashBasedGenerationFunction(AlgorithmID hashAlgorithm,
                           int counterOffset,
                           byte[] otherInfo)

Initialises the class with the provided hash algorithm, a specific starting value, and some additional info Y. The implementation will perform the computation in the following way:

     X := counterOffset
     repeat until T.length >= desired length
          T := T || HASH(Z||I2OSP(X, 4)||Y)
          X := X + 1
 

whereas HASH will be an instance of the requested hashAlgorithm.

Parameters:

hashAlgorithm - the algorithm id of some hash function

counterOffset - the initial value if the counter

otherInfo - some additional (public) information Y

HashBasedGenerationFunction

public HashBasedGenerationFunction(AlgorithmID hashAlgorithm,
                           int counterOffset,
                           byte[] otherInfo,
                           boolean counterFirst)

Initialises the class with the provided hash algorithm, a specific starting value, some additional info Y, and the position of the counter in the digest computation. The implementation will perform the computation in the following way, iff the boolean parameter is set to true:

     X := counterOffset
     repeat until T.length >= desired length
          T := T || HASH(I2OSP(X, 4)||Z||Y)
          X := X + 1
 

Iff the parameter is false, then:

     X := counterOffset
     repeat until T.length >= desired length
          T := T || HASH(Z||I2OSP(X, 4)||Y)
          X := X + 1
 

whereas HASH will be an instance of the requested hashAlgorithm.

Parameters:

hashAlgorithm - the algorithm id of some hash function

counterOffset - the initial value if the counter

otherInfo - some additional (public) information Y

counterFirst - iff true, then the counter will be the first input to the hash computation. iff false, then the counter will be the second input.

Method Detail

generateOctets

public void generateOctets(byte[] seed,
                  int seedOff,
                  int seedLen,
                  int octetsLen,
                  byte[] dst,
                  int dstOff)

Generates the bit string according to the initialisation. See the constructors of this class for the exact way the method computes the output.

Parameters:

seed - the (most likely) seed Z which the method uses for the generation of the output

seedOff - the offset indicating the start position within the seed array

seedLen - the actual number of seed bytes

octetsLen - the number of required octets

dst - the destination array to which to XOR the mask result

dstOff - the offset indicating the start position within the destination array

getHashAlgorithm

public AlgorithmID getHashAlgorithm()

Returns the AlgorithmID of the used hash algorithm.

Returns:

the AlgorithmID of the used hash algorithm.

setHashAlgorithm

public void setHashAlgorithm(AlgorithmID hashAlgorithm)

Sets the AlgorithmID of the hash algorithm which the implementation uses to generate the bit string. This method overrides the algorithm set by the constructor.

Parameters:

hashAlgorithm - the AlgorithmID of the hash algorithm that generateOctets(byte[], int, int, int, byte[], int) should use

engineReset

public void engineReset()

Resets the intern MessageDigest instance.

See Also:

MessageDigest.reset()

setHashEngine

public void setHashEngine(java.security.MessageDigest messageDigest)

Ignores the provided AlgorithmID and directly sets the MessageDigest instance that generateOctets(byte[], int, int, int, byte[], int) uses to generate the output string.

Parameters:

messageDigest - a fresh instance of MessageDigest. It will result in undefined behavior if the instance is already used.

setHashEngine

public void setHashEngine()
                   throws java.security.NoSuchAlgorithmException

Sets/resets the hash engine. This method checks if a hash engine is available. If not, it tries to create one from the hash algorithm id.

Throws:

java.security.NoSuchAlgorithmException - if no hash engine is available

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object