com.entrust.toolkit.security.crypto.digest

Class SHA256

java.lang.Object

java.security.MessageDigestSpi

java.security.MessageDigest

com.entrust.toolkit.security.crypto.digest.SHA256

public final class SHA256
extends java.security.MessageDigest

A software based implementation of the SHA-256 message digest algorithm.

A message digest algorithm represents the functionality of a one-way hash function. A hash function is a computationally efficient function, mapping binary strings (messages) of arbitrary length to binary strings (digests) of some fixed length. Theses algorithms enable the determination of a message's integrity: any change to the message will, with very high probability, result in a different message digest. This property is useful in the generation and verification of digital signatures and message authentication codes, and in the generation of random numbers.

The SHA-256 message digest can process messages of up to 2^64 bits in length, and always produces a 256-bit digest. The algorithm can be described in two stages: pre-processing and hash computation. Pre-processing involves padding a message, parsing the padded message into 512-bit blocks, and setting initialization values to be used in the hash computation. The hash computation generates a message schedule from the padded message and uses that schedule, along with functions, constants, and word operations to iteratively generate a series of hash values. The final hash value generated by the hash computation is used to determine the message digest.

An instance of this algorithm can be obtained using the Java Cryptography Architecture (JCA), by requesting a 'SHA-256' message digest from the Entrust cryptographic service provider. This can be done using the following call:

MessageDigest.getInstance("SHA-256", "Entrust");

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

Since:

7.0

See Also:

FIPS 180-3, Secure Hash Standard (SHS)

Constructor Summary

Constructors

Constructor and Description
SHA256() The constructor; creates a new instance of the SHA-256 message digest algorithm.

Method Summary

Modifier and Type	Method and Description
protected byte[]	engineDigest() Completes the hash computation by performing final operations such as padding.
protected int	engineDigest(byte[] buf, int offset, int len) Completes the hash computation by performing final operations such as padding.
protected int	engineGetDigestLength() Returns the digest length in bytes.
protected void	engineReset() Resets the digest for further use.
protected void	engineUpdate(byte input) Updates the digest using the specified byte.
protected void	engineUpdate(byte[] input, int offset, int length) Updates the digest using the specified array of bytes, starting at the specified offset.

Methods inherited from class java.security.MessageDigest

clone, digest, digest, digest, getAlgorithm, getDigestLength, getInstance, getInstance, getInstance, getProvider, isEqual, reset, toString, update, update, update, update

Methods inherited from class java.security.MessageDigestSpi

engineUpdate

Methods inherited from class java.lang.Object

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

Constructor Detail

SHA256

public SHA256()

The constructor; creates a new instance of the SHA-256 message digest algorithm.

Applications should not use this constructor, instead the message digest algorithm should be requested from the appropriate JCA/JCE cryptographic service provider as follows: MessageDigest.getInstance("SHA-256", "Entrust").

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)

Method Detail

engineUpdate

protected void engineUpdate(byte[] input,
                            int offset,
                            int length)

Updates the digest using the specified array of bytes, starting at the specified offset.

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)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineUpdate in class java.security.MessageDigestSpi

Parameters:

input - [FIPS 140-2 data input] the array of bytes to use for the update.

offset - [FIPS 140-2 data input] the offset to start from in the array of bytes.

length - [FIPS 140-2 data input] the number of bytes to use, starting at offset.

Throws:

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

engineUpdate

protected void engineUpdate(byte input)

Updates the digest using the specified byte.

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)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineUpdate in class java.security.MessageDigestSpi

Parameters:

input - [FIPS 140-2 data input] the byte to use for the update.

Throws:

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

engineDigest

protected byte[] engineDigest()

Completes the hash computation by performing final operations such as padding. Once engineDigest has been called, the engine should be reset (see engineReset). Resetting is the responsibility of the engine implementor.

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)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineDigest in class java.security.MessageDigestSpi

Returns:

[FIPS 140-2 data output] the array of bytes for the resulting hash value.

Throws:

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

engineDigest

protected int engineDigest(byte[] buf,
                           int offset,
                           int len)
                    throws java.security.DigestException

Completes the hash computation by performing final operations such as padding. Once engineDigest has been called, the engine should be reset (see engineReset). Resetting is the responsibility of the engine implementor.

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)
• data input interface (parameters)
• data output interface (parameters, return value)
• status output interface (exceptions)

Overrides:

engineDigest in class java.security.MessageDigestSpi

Parameters:

buf - [FIPS 140-2 data output] the output buffer in which to store the digest

offset - [FIPS 140-2 data input] offset to start from in the output buffer

len - [FIPS 140-2 data input] number of bytes within buf allotted for the digest. Both this default implementation and the SUN provider do not return partial digests. The presence of this parameter is solely for consistency in our API's. If the value of this parameter is less than the actual digest length, the method will throw a DigestException. This parameter is ignored if its value is greater than or equal to the actual digest length.

Returns:

[FIPS 140-2 data output] the length of the digest stored in the output buffer.

Throws:

java.security.DigestException - [FIPS 140-2 status output] if an error occurs.

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

engineReset

protected void engineReset()

Resets the digest for further use.

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)

Specified by:

engineReset in class java.security.MessageDigestSpi

Throws:

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

engineGetDigestLength

protected int engineGetDigestLength()

Returns the digest length in bytes.

FIPS 140-2:

FIPS Service: Query 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 output interface (return value)
• status output interface (exceptions)

Overrides:

engineGetDigestLength in class java.security.MessageDigestSpi

Returns:

[FIPS 140-2 data output] the digest length in bytes.

Throws:

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