PKCS11Mac (IAIK PKCS#11 Provider API Documentation)

java.lang.Object
- javax.crypto.MacSpi
- - iaik.pkcs.pkcs11.provider.macs.PKCS11Mac

All Implemented Interfaces:

PKCS11EngineClass

Direct Known Subclasses:

AesMac, Cast128Mac, Cast3Mac, CastMac, DesEdeMac, DesMac, IdeaMac, Md2HMac, Md5HMac, Rc2Mac, Rc5Mac, RipeMd128HMac, RipeMd160HMac, Sha1HMac, Sha224HMac, Sha256HMac, Sha3_224HMac, Sha3_256HMac, Sha3_384HMac, Sha3_512HMac, Sha384HMac, Sha512_224HMac, Sha512_256HMac, Sha512HMac, SSL3Md5Mac, SSL3Sha1Mac
```
public abstract class PKCS11Mac
extends javax.crypto.MacSpi
implements PKCS11EngineClass
```
This is an implementation of a MAC class that uses the IAIK PKCS#11 wrapper to access the token. It only works with IAIKPKCS11SecretKey. It is the base class for the implementations for the various algorithms. If it is used with non-PKCS#11 keys, keys which are not of the aforementioned classes, it uses a software cipher of the configured delegate provider. It is the base class for the implementations of the various algorithms.

Author:

Karl Scheibelhofer

Field Summary

Fields
Modifier and Type	Field and Description
`protected byte[]`	`buffer_` Buffer to delay the first data block to be able to calculate the MAC in one step.
`protected boolean`	`currentKeyIsSoftwareKey_` Indiecates that the currently used key is a software key.
`protected int`	`defaultMacLength_` The mac length.
`protected boolean`	`initialized_` Indicates, if this object is initialized and ready for encryption or decryption.
`protected IAIKPKCS11SecretKey`	`key_` The key to use for encryption/decryption.
`protected iaik.pkcs.pkcs11.objects.SecretKey`	`keyObject_` The PKCS#11 key object of the current key.
`protected PKCS11MacSpec`	`params_` The params_.
`protected boolean`	`pkcs11OperationInitialized_` Indicates, if the PKCS#11 signature/verify is already initialized for the next operation round.
`protected iaik.pkcs.pkcs11.Session`	`session_` The session this object works with.
`protected javax.crypto.Mac`	`softwareDelegate_` The software implementation, if the currently used key is not a PKCS#11 key.
`protected TokenManager`	`tokenManager_` Token manager used to login session, if required.
`protected boolean`	`updateUsed_` Indicates, if the currently active operation has already used any update function.
`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.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`PKCS11Mac(iaik.pkcs.pkcs11.Mechanism macMechanism, int defaultMacLength)` Instantiates a new pKC s11 mac.
`protected`	`PKCS11Mac(iaik.pkcs.pkcs11.Mechanism macMechanism, iaik.pkcs.pkcs11.Mechanism macGeneralMechanism, int defaultMacLength)` Default constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`checkKeyObject(iaik.pkcs.pkcs11.objects.Key keyObject)` Check the given key object, if it is acceptable for this cipher.
`protected byte[]`	`engineDoFinal()` Returns the calculated MAC value.
`protected int`	`engineGetMacLength()` Returns the length of the calculated MAC value in bytes.
`protected void`	`engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec params)` Initializes this Mac object with given secret key and algorithm parameter specification.
`protected void`	`engineReset()` Resets this Mac object for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.
`protected void`	`engineUpdate(byte input)` Processes the given byte.
`protected void`	`engineUpdate(byte[] data, int offset, int length)` Processes the given number of bytes, supplied in a byte array starting at the given position.
`protected void`	`finalize()` Tries to close the used session.
`protected void`	`finalizePkcs11Operation()` The internal session finalization method, if the current operation has been finished.
`protected abstract java.lang.String`	`getAlgorithmName()` Get the JCA standard name of this signautre algorithm.
`protected iaik.pkcs.pkcs11.Mechanism`	`getMechanism()` Get the current mechanism of this cipher object.
`protected iaik.pkcs.pkcs11.MechanismInfo[][]`	`getUsedMechanismFeatures()` Returns an two-dimensional array of MechanismInfos that this engine class uses.
`protected void`	`initialize()` The internal initialization method, if 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 cipher to delegate software keys operations.
`boolean`	`isSupportedBy(TokenManager tokenManager)` Check, if the current token of the given token manager supports the required features for this engine class.
`protected byte[]`	`pkcs11DoFinal()` Returns the calculated MAC value.
`protected int`	`pkcs11GetMacLength()` Returns the length of the calculated MAC value in bytes.
`protected void`	`pkcs11Init(java.security.Key key, java.security.spec.AlgorithmParameterSpec params)` Initializes this Mac object with given secret key and algorithm parameter specification.
`protected void`	`pkcs11Prepare()` Pkcs11 prepare.
`protected void`	`pkcs11Reset()` Resets this Mac object for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.
`protected void`	`pkcs11Update(byte input)` Processes the given byte.
`protected void`	`pkcs11Update(byte[] data, int offset, int length)` Processes the given number of bytes, supplied in a byte array starting at the given position.

Methods inherited from class javax.crypto.MacSpi
clone, engineUpdate

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - session_
```
protected iaik.pkcs.pkcs11.Session session_
```
    The session this object works with.
  - tokenManager_
```
protected TokenManager tokenManager_
```
    Token manager used to login session, if required.
  - key_
```
protected IAIKPKCS11SecretKey key_
```
    The key to use for encryption/decryption.
  - keyObject_
```
protected iaik.pkcs.pkcs11.objects.SecretKey keyObject_
```
    The PKCS#11 key object of the current key.
  - initialized_
```
protected boolean initialized_
```
    Indicates, if this object is initialized and ready for encryption or decryption.
  - pkcs11OperationInitialized_
```
protected boolean pkcs11OperationInitialized_
```
    Indicates, if the PKCS#11 signature/verify is already initialized for the next operation round.
  - updateUsed_
```
protected boolean updateUsed_
```
    Indicates, if the currently active operation has already used any update function.
  - buffer_
```
protected byte[] buffer_
```
    Buffer to delay the first data block to be able to calculate the MAC in one step.
  - currentKeyIsSoftwareKey_
```
protected boolean currentKeyIsSoftwareKey_
```
    Indiecates that the currently used key is a software key.
  - softwareDelegate_
```
protected javax.crypto.Mac softwareDelegate_
```
    The software implementation, if the currently used key is not a PKCS#11 key.
  - 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.
  - params_
```
protected PKCS11MacSpec params_
```
    The params_.
  - defaultMacLength_
```
protected int defaultMacLength_
```
    The mac length.
- Constructor Detail
  - PKCS11Mac
```
protected PKCS11Mac(iaik.pkcs.pkcs11.Mechanism macMechanism,
                    int defaultMacLength)
```
    Instantiates a new pKC s11 mac.
    
    Parameters:
    
    macMechanism - the mac mechanism
    
    defaultMacLength - the default mac length
  - PKCS11Mac
```
protected PKCS11Mac(iaik.pkcs.pkcs11.Mechanism macMechanism,
                    iaik.pkcs.pkcs11.Mechanism macGeneralMechanism,
                    int defaultMacLength)
```
    Default constructor.
    
    Parameters:
    
    macMechanism - the mac mechanism
    
    macGeneralMechanism - the mac general mechanism
    
    defaultMacLength - the default mac length for this mechanism
- Method Detail
  - 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)
  - checkKeyObject
```
protected void checkKeyObject(iaik.pkcs.pkcs11.objects.Key keyObject)
                       throws java.security.InvalidKeyException
```
    Check the given key object, if it is acceptable for this cipher. Throw an exception, if not.
    
    Parameters:
    
    keyObject - The key object to check.
    
    Throws:
    
    java.security.InvalidKeyException - If this cipher cannot work with this type of key object.
    
    Preconditions:
    
    (key <> null)
  - engineDoFinal
```
protected byte[] engineDoFinal()
                        throws java.lang.IllegalStateException
```
    Returns the calculated MAC value.
    After the MAC finally has been calculated, the MAC object is reset for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object. This implementation delegates this call to the software provider, if the current key is a software key. If the key is a key of this provider, it delegates the call to the corresponding pkcs11 method with prefix pkcs11 instead of engine.
    
    Specified by:
    
    engineDoFinal in class javax.crypto.MacSpi
    
    Returns:
    
    the calculated MAC value in a byte array
    
    Throws:
    
    java.lang.IllegalStateException - if this MAC is in not in a proper state for performing a engineDoFinal operation
    
    Postconditions:
    
    (result <> null)
  - pkcs11DoFinal
```
protected byte[] pkcs11DoFinal()
                        throws java.lang.IllegalStateException
```
    Returns the calculated MAC value.
    After the MAC finally has been calculated, the MAC object is reset for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.
    
    Returns:
    
    the calculated MAC value in a byte array
    
    Throws:
    
    java.lang.IllegalStateException - if this MAC is in not in a proper state for performing a engineDoFinal operation
    
    Postconditions:
    
    (result <> null)
  - engineGetMacLength
```
protected int engineGetMacLength()
```
    Returns the length of the calculated MAC value in bytes. This implementation delegates this call to the software provider, if the current key is a software key. If the key is a key of this provider, it delegates the call to the corresponding pkcs11 method with prefix pkcs11 instead of engine.
    
    Specified by:
    
    engineGetMacLength in class javax.crypto.MacSpi
    
    Returns:
    
    the MAC value length in bytes.
  - pkcs11GetMacLength
```
protected int pkcs11GetMacLength()
```
    Returns the length of the calculated MAC value in bytes.
    
    Returns:
    
    the MAC value length in bytes.
  - engineInit
```
protected void engineInit(java.security.Key key,
                          java.security.spec.AlgorithmParameterSpec params)
                   throws java.security.InvalidKeyException,
                          java.security.InvalidAlgorithmParameterException
```
    Initializes this Mac object with given secret key and algorithm parameter specification. This implementation delegates this call to the software provider, if the key is a software key. If the key is a key of this provider, it delegates the call to the corresponding pkcs11 method with prefix pkcs11 instead of engine.
    
    Specified by:
    
    engineInit in class javax.crypto.MacSpi
    
    Parameters:
    
    key - the secret key for initializing this MAC object.
    
    params - the algorithm parameter specification.
    
    Throws:
    
    java.security.InvalidKeyException - if the given key cannot be used for initializing this MAC object
    
    java.security.InvalidAlgorithmParameterException - if the given algorithm parameters do not match to this MAC object
    
    Preconditions:
    
    (key <> null)
  - initializeSoftwareDelegate
```
protected void initializeSoftwareDelegate()
```
    Instantiate a new software cipher to delegate software keys operations.
  - getAlgorithmName
```
protected abstract java.lang.String getAlgorithmName()
```
    Get the JCA standard name of this signautre algorithm.
    
    Returns:
    
    The JCA standard name of this signautre algorithm.
    
    Postconditions:
    
    (result <> null)
  - pkcs11Init
```
protected void pkcs11Init(java.security.Key key,
                          java.security.spec.AlgorithmParameterSpec params)
                   throws java.security.InvalidKeyException,
                          java.security.InvalidAlgorithmParameterException
```
    Initializes this Mac object with given secret key and algorithm parameter specification.
    
    Parameters:
    
    key - the secret key for initializing this MAC object.
    
    params - the algorithm parameter specification.
    
    Throws:
    
    java.security.InvalidKeyException - if the given key cannot be used for initializing this MAC object
    
    java.security.InvalidAlgorithmParameterException - if the given algorithm parameters do not match to this MAC object
    
    Preconditions:
    
    (key <> null) and (key instanceof IAIKPKCS11SecretKey)
  - engineReset
```
protected void engineReset()
```
    Resets this Mac object for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object. This implementation delegates this call to the software provider, if the current key is a software key. If the key is a key of this provider, it delegates the call to the corresponding pkcs11 method with prefix pkcs11 instead of engine.
    
    Specified by:
    
    engineReset in class javax.crypto.MacSpi
  - pkcs11Reset
```
protected void pkcs11Reset()
```
    Resets this Mac object for being able to be used for further MAC computations, either by using the same secret key again, or using a new key by properly re-initializing this MAC object.
  - pkcs11Prepare
```
protected void pkcs11Prepare()
                      throws java.lang.IllegalStateException,
                             IAIKPkcs11Exception
```
    Pkcs11 prepare. This helper method checks the initialization status of the MAC engine as well as of the underlying pkcs11 module. If the MAC engine is not initialized yet an exception is thrown. If the pkcs11 module is not initialized yet this method tries to initialize it. If unsuccessful, the pkcs11 session is finalized and an exception is raised.
    
    Throws:
    
    java.lang.IllegalStateException - if this MAC engine was not initialized yet
    
    IAIKPkcs11Exception - if initialization of the underlying pkcs11 module fails
  - engineUpdate
```
protected void engineUpdate(byte input)
                     throws java.lang.IllegalStateException
```
    Processes the given byte. This implementation delegates this call to the software provider, if the current key is a software key. If the key is a key of this provider, it delegates the call to the corresponding pkcs11 method with prefix pkcs11 instead of engine.
    
    Specified by:
    
    engineUpdate in class javax.crypto.MacSpi
    
    Parameters:
    
    input - the byte to be processed.
    
    Throws:
    
    java.lang.IllegalStateException - if this MAC is in not in a proper state for performing a engineUpdate operation
  - pkcs11Update
```
protected void pkcs11Update(byte input)
                     throws java.lang.IllegalStateException
```
    Processes the given byte.
    
    Parameters:
    
    input - the byte to be processed.
    
    Throws:
    
    java.lang.IllegalStateException - if this MAC is in not in a proper state for performing a engineUpdate operation
  - engineUpdate
```
protected void engineUpdate(byte[] data,
                            int offset,
                            int length)
                     throws java.lang.IllegalStateException
```
    Processes the given number of bytes, supplied in a byte array starting at the given position. This implementation delegates this call to the software provider, if the current key is a software key. If the key is a key of this provider, it delegates the call to the corresponding pkcs11 method with prefix pkcs11 instead of engine.
    
    Specified by:
    
    engineUpdate in class javax.crypto.MacSpi
    
    Parameters:
    
    data - the byte array holding the data to be processed
    
    offset - the offset indicating the start position within the input byte array
    
    length - the number of bytes to be processed
    
    Throws:
    
    java.lang.IllegalStateException - if this MAC is in not in a proper state for performing a engineUpdate operation
    
    Preconditions:
    
    (data <> null) and ((offset + length) <= data.length)
  - pkcs11Update
```
protected void pkcs11Update(byte[] data,
                            int offset,
                            int length)
                     throws java.lang.IllegalStateException
```
    Processes the given number of bytes, supplied in a byte array starting at the given position.
    
    Parameters:
    
    data - the byte array holding the data to be processed
    
    offset - the offset indicating the start position within the input byte array
    
    length - the number of bytes to be processed
    
    Throws:
    
    java.lang.IllegalStateException - if this MAC is in not in a proper state for performing a engineUpdate operation
    
    Preconditions:
    
    (data <> null) and ((offset + length) <= data.length)
  - getMechanism
```
protected iaik.pkcs.pkcs11.Mechanism getMechanism()
```
    Get the current mechanism of this cipher object. This may change with the mode of operation and padding. This mechanism must also include any required parameter objects. This method can expect that the key_ object is already correctly set. For this key the method must return an appropriate mechanism.
    
    Returns:
    
    The mechanism this object uses for encryption and decryption. If the currently set combination of mode and padding is unsupported, this method returns null.
  - initializeSession
```
protected void initializeSession()
```
    Sets up an appropriate session. The key must be set before.
  - 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 initializing the signing operation fails.
  - finalizePkcs11Operation
```
protected void finalizePkcs11Operation()
```
    The internal session finalization method, if the current operation has been finished.
  - initialize
```
protected void initialize()
                   throws java.security.InvalidAlgorithmParameterException,
                          java.security.InvalidKeyException
```
    The internal initialization method, if all necessary member variables are set.
    
    Throws:
    
    java.security.InvalidAlgorithmParameterException - If the parameter specs are invalid.
    
    java.security.InvalidKeyException - If the key is invalid for this operation.
  - 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 disposing the session 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 PKCS11Mac

Field Summary

Constructor Summary

Method Summary

Methods inherited from class javax.crypto.MacSpi

Methods inherited from class java.lang.Object

Field Detail

session_

tokenManager_

key_

keyObject_

initialized_

pkcs11OperationInitialized_

updateUsed_

buffer_

currentKeyIsSoftwareKey_

softwareDelegate_

usedMechanisms_

usedMechanismInfos_

params_

defaultMacLength_

Constructor Detail

PKCS11Mac

PKCS11Mac

Method Detail

getUsedMechanismFeatures

isSupportedBy

checkKeyObject

engineDoFinal

pkcs11DoFinal

engineGetMacLength

pkcs11GetMacLength

engineInit

initializeSoftwareDelegate

getAlgorithmName

pkcs11Init

engineReset

pkcs11Reset

pkcs11Prepare

engineUpdate

pkcs11Update

engineUpdate

pkcs11Update

getMechanism

initializeSession

initializePkcs11Operation

finalizePkcs11Operation

initialize

finalize