com.entrust.toolkit.capi

Class CryptHash

java.lang.Object

com.entrust.toolkit.credentials.Handle

com.entrust.toolkit.capi.CapiHandle

com.entrust.toolkit.capi.CryptHash

public class CryptHash
extends CapiHandle

This class encapsulates information about a handle to a CAPI Hash object. It is analogous the CAPI HCRYPTHASH type, and is used for all situations where an HCRYPTHASH is required for a native call. If it was obtained from a CSP with a private signing key available, it can also be used to sign the hashed data.

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

Field Summary

Fields inherited from class com.entrust.toolkit.credentials.Handle

m_handle

Method Summary

Modifier and Type	Method and Description
void	close() Closes the handle to the native hash object, releasing memory and resource.
HashAlgorithms	getAlgorithm() Return the hash algorithm id of this hash object.
static CryptHash	getHashInstance(CryptProvider provider, HashAlgorithms hashAlg) Creates and returns a CAPI hash with the given algorithm, associated with the given provider.
int	getHashSize() Returns the hash size.
byte[]	getHashValue() Completes the hash computation and returns the hash value.
CryptProvider	getProvider() Return the handle to the provider of this hash object.
byte[]	getSignedHash() Signs the current hash value and returns the bytes of the signature.
void	setHashValue(byte[] hashValue) Sets the actual bytes of the hash, so that an arbitrary byte array can be signed.
void	update(byte[] input, int offset, int length) Updates the hash with the given input data, starting at the given offset, and hashing the given length.

Methods inherited from class com.entrust.toolkit.capi.CapiHandle

debugInfo, debugInfo, equals, setExtendedDebugging

Methods inherited from class com.entrust.toolkit.credentials.Handle

clearHandle, finalize, getHandle, hashCode

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

getHashInstance

public static CryptHash getHashInstance(CryptProvider provider,
                                        HashAlgorithms hashAlg)
                                 throws CapiException

Creates and returns a CAPI hash with the given algorithm, associated with the given provider.

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

Parameters:

provider - [FIPS 140-2 control input] The CSP that provides the desired hash algorithm.

hashAlg - [FIPS 140-2 control input] The hash algorithm

Returns:

[FIPS 140-2 status output] a CAPI hash object of the given type.

Throws:

CapiException - [FIPS 140-2 status output] if the specified provider cannot provide the requested hash algorithm.

close

public void close()

Closes the handle to the native hash object, releasing memory and resource. No calls to this object can be made after calling this method.

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:

close in class Handle

getHashSize

public int getHashSize()

Returns the hash size. This is the value returned from a call to CryptGetHashParam specifying HP_HASHSIZE as the parameter.

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)

Returns:

[FIPS 140-2 data output] the hash size.

Throws:

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

See Also:

MSDN library documentation for CryptGetHashParam

getProvider

public CryptProvider getProvider()

Return the handle to the provider of this hash object.

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)

Returns:

[FIPS 140-2 data output] the handle to the provider of this hash object.

Throws:

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

getAlgorithm

public HashAlgorithms getAlgorithm()

Return the hash algorithm id of this hash object.

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)

Returns:

[FIPS 140-2 data output] the hash algorithm id of this hash object.

Throws:

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

update

public void update(byte[] input,
                   int offset,
                   int length)
            throws CapiException

Updates the hash with the given input data, starting at the given offset, and hashing the given length.

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)

Parameters:

input - [FIPS 140-2 data input] The data to hash

offset - [FIPS 140-2 data input] The starting offset

length - [FIPS 140-2 data input] The number of bytes to hash

Throws:

CapiException - [FIPS 140-2 status output] The there is any problem updating the hash

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

getHashValue

public byte[] getHashValue()
                    throws CapiException

Completes the hash computation and returns the hash value. No further calls to update can be made after this call.

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)

Returns:

[FIPS 140-2 data output] the completed message hash.

Throws:

CapiException - [FIPS 140-2 status output] if there is any problem computing the hash value.

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

setHashValue

public void setHashValue(byte[] hashValue)
                  throws CapiException

Sets the actual bytes of the hash, so that an arbitrary byte array can be signed. This may have been calculated by some other hashing mechanism. Note that not all hash objects or CSPs support this operation, and it should only be used under very special circumstances.

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:

hashValue - [FIPS 140-2 data input] The hash value to set. The length must be equal to that reported by getHashSize().

Throws:

CapiException - [FIPS 140-2 status output] if there is a problem setting the hash value.

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

See Also:

MSDN library documentation for CryptSetHashParam

getSignedHash

public byte[] getSignedHash()
                     throws CapiException

Signs the current hash value and returns the bytes of the signature. This can only be done if this hash object was created with a provider that has a signing key available.

FIPS 140-2:

FIPS Service: Digital Signature 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)

Returns:

[FIPS 140-2 data output] the signed hash. For an RSA signature, this will be signature as per PKCS#1. For a DSA signature, this will be the 40 byte pair (s, r), with s and r in big-endian form. Note the reversal from the usual (r,s) form.

Throws:

CapiException - [FIPS 140-2 status output] if there is a problem signing the hash.

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