com.entrust.toolkit.security.crypto.digest

Class CapiDigest

java.lang.Object

java.security.MessageDigestSpi

java.security.MessageDigest

com.entrust.toolkit.security.crypto.digest.CapiDigest

Direct Known Subclasses:

Md5Capi, Sha1Capi, Sha256Capi, Sha384Capi, Sha512Capi, Ssl3ShaMd5Capi

public abstract class CapiDigest
extends java.security.MessageDigest

The super-class of all MS-CAPI based message digest algorithm implementations (the digest operation is performed natively in MS-CAPI).

An MS-CAPI based message digest algorithm instance can be obtained using the Java Cryptography Architecture (JCA), by requesting the '<algorithm>' algorithm from the Entrust cryptographic service provider. This can be done using the following call:

Message.getInstance("<algorithm>", "Entrust");

Notes:

This class requires an extra initialization step after MessageDigest.getInstance() is called. A message digest in CAPI is associated with a Cryptographic Service Provider (CSP), so a handle to provider is required. This must be set with a call to createCapiHash() before any of the engine methods are called. Also, the CAPI hash object returned by getHash() must be explicitly closed after the digesting procedure is completed.

The reset method is not currently supported, a new digest instance must be obtained for each digest computation.

The only time that digesting must be done in CAPI is when signing data. The Signature classes included with the Toolkit will handle this automatically, so there should be no need to explicitly use CAPI to calculate a message digest.

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

Method Summary

Modifier and Type	Method and Description
void	closeHash() Closes any open handles to native CAPI objects referenced by this hash object.
void	createCapiHash(CryptProvider provider) Create the internal native CAPI hasher.
protected byte[]	engineDigest() 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.
CryptHash	getHash() Returns a reference to the internal CAPI hasher.

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

engineDigest, engineUpdate

Methods inherited from class java.lang.Object

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

Method Detail

getHash

public final CryptHash getHash()

Returns a reference to the internal CAPI hasher. This may seem unusual, but it is required to get signature values out of CAPI.

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

Returns:

[FIPS 140-2 status output] a reference to the internal CAPI hasher

closeHash

public void closeHash()

Closes any open handles to native CAPI objects referenced by this hash object.

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)

createCapiHash

public void createCapiHash(CryptProvider provider)
                    throws CapiException

Create the internal native CAPI hasher. This method MUST be called before any of the engine methods, or a NullPointerException will be thrown.

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:

provider - [FIPS 140-2 control output] the CAPI CSP which will provide the native hashing capability.

Throws:

CapiException - [FIPS 140-2 status output] if the hashing algorithm is not SHA1 or MD5, or if the CSP does not support the hash algorithm.

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.

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.

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

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

engineGetDigestLength

protected final 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