com.entrust.toolkit.util

Class ExtendedHasher

java.lang.Object

com.entrust.toolkit.util.ExtendedHasher

public class ExtendedHasher
extends java.lang.Object

The extended hasher provides a simple utility for repeatedly hashing data a given number of times, and returning an arbitrary number of bytes based on the original data.

Internally the following is done until the required number of bits are achieved:

output = Hn( input ) || Hn( input || 0x01 ) || Hn( input || 0x02 ) ... where Hn( x ) is n iterations of hash function H applied to data x

The requested output is created by truncating the above result. Any additional bytes that are created but not needed are saved and returned on the next request for output.

If several calls are made to request output without resetting the input, the internal counter (that is appended to the input before hashing) will not be reset. This ensures that unique results are obtained even if the extended hasher is not reset.

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

Constructor Summary

Constructors

Constructor and Description
ExtendedHasher() The default constructor; creates and initializes an ExtendedHasher object that uses the 'SHA1' hashing algorithm.
ExtendedHasher(java.security.MessageDigest messageDigest) A constructor; creates and initializes an ExtendedHasher object that uses the provided MessageDigest to do the hashing.
ExtendedHasher(java.lang.String algorithm) A constructor; creates and initializes an ExtendedHasher object that uses the specified hashing algorithm to do the hashing.

Method Summary

Methods

Modifier and Type	Method and Description
static byte[]	concatenate(byte[] ba1, byte[] ba2) Deprecated. since 6.1; use ByteArray.append(byte[]) instead
byte[]	getOutput(int numBytes, int iterations) Hashes the input byte array the specified number of times and returns the requested number of bytes.
void	setInput(byte[] input) Sets the input byte array to be used by the extended hasher, and resets all internal data in preparation for a new hashing session.
static byte[]	tail(byte[] ba, int offset) Deprecated. since 6.1; use ByteArray.tail(int) instead
static byte[]	truncate(byte[] ba, int length) Deprecated. since 6.1; use ByteArray.truncate(int) instead
void	wipe() Wipes all internal data.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExtendedHasher

public ExtendedHasher()

The default constructor; creates and initializes an ExtendedHasher object that uses the 'SHA1' hashing algorithm.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

ExtendedHasher

public ExtendedHasher(java.lang.String algorithm)
               throws java.security.NoSuchAlgorithmException

A constructor; creates and initializes an ExtendedHasher object that uses the specified hashing algorithm to do the hashing.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Parameters:

algorithm - [FIPS 140-2 control input] a hashing algorithm

Throws:

java.security.NoSuchAlgorithmException - [FIPS 140-2 status output] thrown if the hashing algorithm is not recognized

ExtendedHasher

public ExtendedHasher(java.security.MessageDigest messageDigest)
               throws java.lang.IllegalArgumentException

A constructor; creates and initializes an ExtendedHasher object that uses the provided MessageDigest to do the hashing.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Parameters:

messageDigest - [FIPS 140-2 control input] a MessageDigest that will be used for all hashing

Throws:

java.lang.IllegalArgumentException - [FIPS 140-2 status output] thrown if the parameter is null

Method Detail

setInput

public void setInput(byte[] input)
              throws java.lang.IllegalArgumentException

Sets the input byte array to be used by the extended hasher, and resets all internal data in preparation for a new hashing session.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• status output interface (exceptions)

Parameters:

input - [FIPS 140-2 data input] the input byte array

Throws:

java.lang.IllegalArgumentException - [FIPS 140-2 status output] thrown if the input byte array is null

getOutput

public byte[] getOutput(int numBytes,
               int iterations)
                 throws java.lang.IllegalArgumentException,
                        java.lang.NullPointerException

Hashes the input byte array the specified number of times and returns the requested number of bytes.

Internally this does the following:

output = Hn( input ) || Hn( input || 0x01 ) || Hn( input || 0x02 ) ... where Hn( x ) is n iterations of hash function H applied to data x

It hashes the input the specified number of times and then checks if the result contains at least the amount of requested data. If not it does the process again, this time appending byte 0x01 to the input, and then appending this result to the previous result. This process continues with the byte that is appended increasing by one each round until the desired number of bytes are achieved.

FIPS 140-2:

FIPS Service: Hash Generation

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data output interface (return value)
• status output interface (exceptions)

Parameters:

numBytes - [FIPS 140-2 control input] the number of bytes requested

iterations - [FIPS 140-2 control input] the number of times to hash the input

Returns:

[FIPS 140-2 data output] the hashed result

Throws:

java.lang.IllegalArgumentException - [FIPS 140-2 status output] thrown if the requested number of bytes is less than zero, or if the requested number of iterations is less than one (at least one hashing round must be done)

java.lang.NullPointerException - [FIPS 140-2 status output] thrown if the input data has not been set yet

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

wipe

public final void wipe()

Wipes all internal data.

FIPS 140-2:

FIPS Service: Zeroization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

concatenate

public static final byte[] concatenate(byte[] ba1,
                 byte[] ba2)

Deprecated. since 6.1; use ByteArray.append(byte[]) instead

Returns the concatenation of two byte arrays.

The resulting array will contain a copy of the contents of the first byte array followed by a copy of the contents of the second.

FIPS 140-2:

FIPS Service: Non-Cryptographic Operation

This API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; it is a helper utility that does not perform any cryptographic function

Parameters:

ba1 - the first byte array

ba2 - the second byte array

Returns:

the concatenation of the two byte arrays

truncate

public static final byte[] truncate(byte[] ba,
              int length)
                             throws java.lang.IllegalArgumentException

Deprecated. since 6.1; use ByteArray.truncate(int) instead

Truncates the end of a byte array.

All bytes after the indicated length are discarded.

FIPS 140-2:

FIPS Service: Non-Cryptographic Operation

This API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; it is a helper utility that does not perform any cryptographic function

Parameters:

ba - the byte array to truncate

length - the new length for the truncated array in bytes

Returns:

the truncated array

Throws:

java.lang.IllegalArgumentException - thrown if length is less than zero, or greater than the length of the byte array

tail

public static final byte[] tail(byte[] ba,
          int offset)
                         throws java.lang.IllegalArgumentException

Deprecated. since 6.1; use ByteArray.tail(int) instead

Truncates the beginning of a byte array.

All bytes before the indicated offset are discarded.

FIPS 140-2:

FIPS Service: Non-Cryptographic Operation

This API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; it is a helper utility that does not perform any cryptographic function

Parameters:

ba - the byte array take the tail of

offset - the offset at which to begin the new byte array

Returns:

the tail of the byte array

Throws:

java.lang.IllegalArgumentException - thrown if the offset is less than zero, or greater than the length of the byte array