PKCS11Hash (IAIK PKCS#11 Provider API Documentation)

java.lang.Object
- java.security.MessageDigestSpi
- - java.security.MessageDigest
  - - iaik.pkcs.pkcs11.provider.hashes.PKCS11Hash

All Implemented Interfaces:

PKCS11EngineClass

Direct Known Subclasses:

FastHash, Md2, Md5, RipeMd128, RipeMd160, Sha1, Sha224, Sha256, Sha3_224, Sha3_256, Sha3_384, Sha3_512, Sha384, Sha512, Sha512_224, Sha512_256
```
public abstract class PKCS11Hash
extends java.security.MessageDigest
implements PKCS11EngineClass
```
This class implements a generic digest algorithm that uses a PKCS#11 token to claculate the hash value. This message digest object gets its provider instance by calling getProvider(). It binds to the token of this provider instance.

Author:

Karl Scheibelhofer

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`hashValueLength_` The length of the hash value produced by this hash.
`protected boolean`	`initialized_` Indicate that this object is initialized.
`protected iaik.pkcs.pkcs11.Mechanism`	`mechanism_` The current cryptoki mechanism to use.
`protected boolean`	`pkcs11OperationInitialized_` Indicates, if the PKCS#11 session is already initialized for the next operation round.
`protected iaik.pkcs.pkcs11.Session`	`session_` The session this object works with.
`protected java.security.MessageDigest`	`softwareDelegate_` If the current token does not support the required mechanism and software delegation is enabled, this variable holds the software delegate.
`protected TokenManager`	`tokenManager_` Token manager used to login session, if required.
`protected iaik.pkcs.pkcs11.MechanismInfo[][]`	`usedMechanismInfos_` The mechanism info is the same for all digest mechanisms.
`protected iaik.pkcs.pkcs11.Mechanism[]`	`usedMechanisms_` The list of used mechanisms.
`protected boolean`	`useSoftwareDelegate_` If set to true, this engine uses the software delegate.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`PKCS11Hash(java.lang.String algorithmName, int hashValueLength, iaik.pkcs.pkcs11.Mechanism mechanism)` Default constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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[] data, int offset, int length)` Updates the digest using the specified array of bytes, starting at the specified offset.
`protected void`	`finalize()` Tries to close the used session.
`protected void`	`finalizePkcs11Operation()` The internal session finalization method, if the current operation has been finished.
`TokenManager`	`getTokenManager()` Get the manager of the token that processes this digest.
`iaik.pkcs.pkcs11.Mechanism`	`getUsedMechanism()`
`protected iaik.pkcs.pkcs11.MechanismInfo[][]`	`getUsedMechanismFeatures()` Returns an two-dimensional array of MechanismInfos that this engine class uses.
`protected iaik.pkcs.pkcs11.Mechanism[]`	`getUsedMechanisms()` Returns an array of Mechanisms that this engine class uses.
`protected void`	`initialize()` The internal initialization method, here all necessary member variables are set.
`protected void`	`initializePkcs11Operation()` The internal session initialization method, if all necessary member variables are set.
`protected void`	`initializeSession()` Sets up an appropriate session.
`protected void`	`initializeSoftwareDelegate()` Instantiate a new software hash to delegate operations.
`boolean`	`isSupportedBy(TokenManager tokenManager)` Check, if the current token of the given token manager supports the required features for this engine class.
`void`	`setTokenManager(TokenManager tokenManager)` Set the manager of the token that processes this digest.

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, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - tokenManager_
```
protected TokenManager tokenManager_
```
    Token manager used to login session, if required.
  - session_
```
protected iaik.pkcs.pkcs11.Session session_
```
    The session this object works with.
  - hashValueLength_
```
protected int hashValueLength_
```
    The length of the hash value produced by this hash.
  - mechanism_
```
protected iaik.pkcs.pkcs11.Mechanism mechanism_
```
    The current cryptoki mechanism to use.
  - usedMechanisms_
```
protected iaik.pkcs.pkcs11.Mechanism[] usedMechanisms_
```
    The list of used mechanisms.
  - usedMechanismInfos_
```
protected iaik.pkcs.pkcs11.MechanismInfo[][] usedMechanismInfos_
```
    The mechanism info is the same for all digest mechanisms.
  - initialized_
```
protected boolean initialized_
```
    Indicate that this object is initialized.
  - pkcs11OperationInitialized_
```
protected boolean pkcs11OperationInitialized_
```
    Indicates, if the PKCS#11 session is already initialized for the next operation round.
  - useSoftwareDelegate_
```
protected boolean useSoftwareDelegate_
```
    If set to true, this engine uses the software delegate.
  - softwareDelegate_
```
protected java.security.MessageDigest softwareDelegate_
```
    If the current token does not support the required mechanism and software delegation is enabled, this variable holds the software delegate.
- Constructor Detail
  - PKCS11Hash
```
protected PKCS11Hash(java.lang.String algorithmName,
                     int hashValueLength,
                     iaik.pkcs.pkcs11.Mechanism mechanism)
```
    Default constructor.
    
    Parameters:
    
    algorithmName - The name of this hash algorithm.
    
    hashValueLength - The length of the producted hash value in bytes; e.g. 20 for SHA-1.
    
    mechanism - The PKCS#11 mechanism of this hash.
    
    Preconditions:
    
    (hashValueLength >= 0) and (mechanism <> null)
- Method Detail
  - engineGetDigestLength
```
protected int engineGetDigestLength()
```
    Returns the digest length in bytes.
    
    Overrides:
    
    engineGetDigestLength in class java.security.MessageDigestSpi
    
    Returns:
    
    The digest length in bytes.
    
    Postconditions:
    
    (result >= 0)
  - engineUpdate
```
protected void engineUpdate(byte input)
```
    Updates the digest using the specified byte.
    
    Specified by:
    
    engineUpdate in class java.security.MessageDigestSpi
    
    Parameters:
    
    input - the byte to use for the update.
  - engineUpdate
```
protected void engineUpdate(byte[] data,
                            int offset,
                            int length)
```
    Updates the digest using the specified array of bytes, starting at the specified offset.
    
    Specified by:
    
    engineUpdate in class java.security.MessageDigestSpi
    
    Parameters:
    
    data - the array of bytes to use for the update.
    
    offset - the offset to start from in the array of bytes.
    
    length - the number of bytes to use, starting at offset.
    
    Preconditions:
    
    (data <> null) and ((offset + length) <= data.length)
  - 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.
    
    Specified by:
    
    engineDigest in class java.security.MessageDigestSpi
    
    Returns:
    
    the array of bytes for the resulting hash value.
    
    Postconditions:
    
    (result <> null)
  - engineReset
```
protected void engineReset()
```
    Resets the digest for further use.
    
    Specified by:
    
    engineReset in class java.security.MessageDigestSpi
  - getUsedMechanisms
```
protected iaik.pkcs.pkcs11.Mechanism[] getUsedMechanisms()
```
    Returns an array of Mechanisms that this engine class uses. For each of this mechanisms, the engine must provide at least one MechanismInfo via the getRequiredMechanismFeatures() method.
    
    Returns:
    
    An array that includes all used pkcs#11 mechanisms. The token must support at least one of these mechanisms. The dimension is equal to the first array dimension of getUsedMechanismFeatures(). May be empty, but must not be null.
    
    Postconditions:
    
    (result <> null) and (result.length == getUsedMechanismFeatures().length)
  - getUsedMechanism
```
public iaik.pkcs.pkcs11.Mechanism getUsedMechanism()
```
  - getUsedMechanismFeatures
```
protected iaik.pkcs.pkcs11.MechanismInfo[][] getUsedMechanismFeatures()
```
    Returns an two-dimensional array of MechanismInfos that this engine class uses. For each mechanism used by this engine, the engine must provide at least one MechanismInfo. The first dimension (index) of the returned array corresponds to the used mechanism as returned by getUsedMechanisms(). The array at this index is the list of used feature combinations used by this engine. The current token must at least support one mechanism and one of the feature combinations (expressed as a MechanismInfo) of the same machanism.
    
    Returns:
    
    An two-dimensional array that includes MechanismInfo objects. The first dimension is equal to the array dimension of getUsedMechanisms(). The token must at least supprot one of these features.
    
    Postconditions:
    
    (result <> null) and (result.length > 0) and (result.length == getUsedMechanisms().length)
  - isSupportedBy
```
public boolean isSupportedBy(TokenManager tokenManager)
```
    Check, if the current token of the given token manager supports the required features for this engine class.
    
    Specified by:
    
    isSupportedBy in interface PKCS11EngineClass
    
    Parameters:
    
    tokenManager - The token manager. Used to get information about the current token.
    
    Returns:
    
    True, if this engine class can be used with the currently present token of the given token manager.
    
    Preconditions:
    
    (tokenManager <> null)
  - getTokenManager
```
public TokenManager getTokenManager()
```
    Get the manager of the token that processes this digest.
    
    Returns:
    
    The manager of the token that processes this digest.
    
    Postconditions:
    
    (result <> null)
  - initialize
```
protected void initialize()
```
    The internal initialization method, here all necessary member variables are set.
  - initializeSession
```
protected void initializeSession()
                          throws iaik.pkcs.pkcs11.TokenException
```
    Sets up an appropriate session. The key must be set before.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If opening or login of the session fails.
  - initializePkcs11Operation
```
protected void initializePkcs11Operation()
                                  throws iaik.pkcs.pkcs11.TokenException
```
    The internal session initialization method, if all necessary member variables are set.
    
    Throws:
    
    iaik.pkcs.pkcs11.TokenException - If the key is invalid for this operation.
  - finalizePkcs11Operation
```
protected void finalizePkcs11Operation()
```
    The internal session finalization method, if the current operation has been finished.
  - initializeSoftwareDelegate
```
protected void initializeSoftwareDelegate()
```
    Instantiate a new software hash to delegate operations.
  - setTokenManager
```
public void setTokenManager(TokenManager tokenManager)
```
    Set the manager of the token that processes this digest.
    
    Parameters:
    
    tokenManager - The manager of the token that processes this digest.
    
    Preconditions:
    
    (tokenManager <> null)
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Tries to close the used session.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable - If finalization fails.

IAIK JavaSecurity Website https://jce.iaik.tugraz.at/

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2023 IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved. Version 1.9.4

Class PKCS11Hash

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.security.MessageDigest

Methods inherited from class java.security.MessageDigestSpi

Methods inherited from class java.lang.Object

Field Detail

tokenManager_

session_

hashValueLength_

mechanism_

usedMechanisms_

usedMechanismInfos_

initialized_

pkcs11OperationInitialized_

useSoftwareDelegate_

softwareDelegate_

Constructor Detail

PKCS11Hash

Method Detail

engineGetDigestLength

engineUpdate

engineUpdate

engineDigest

engineReset

getUsedMechanisms

getUsedMechanism

getUsedMechanismFeatures

isSupportedBy

getTokenManager

initialize

initializeSession

initializePkcs11Operation

finalizePkcs11Operation

initializeSoftwareDelegate

setTokenManager

finalize