iaik.pkcs.pkcs11.provider.keyagreements

Class PKCS11KeyAgreement

java.lang.Object

javax.crypto.KeyAgreementSpi

iaik.pkcs.pkcs11.provider.keyagreements.PKCS11KeyAgreement

All Implemented Interfaces:

PKCS11EngineClass

Direct Known Subclasses:

DhKeyAgreement, EcDhKeyAgreement, X942DhKeyAgreement

public abstract class PKCS11KeyAgreement
extends javax.crypto.KeyAgreementSpi
implements PKCS11EngineClass

This is a generic base implementation for a key agreement. It serves as base class for concrete implementations that use a PKCS#11 token to calculate the cryptographic operations. This implementation must be initialized using a PKCS11KeyAgreementSpec. Other types of initialization are unsupported. This is necessary, because this implementation requires certain information for PKCS#11 operations, which it cannot get by other means.

Author:

Karl Scheibelhofer

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	currentKeyIsSoftwareKey_ Indicates that the currently used key is a software key.
protected boolean	initialized_ Indicates, if this object is initialized and ready for signing or verification.
protected IAIKPKCS11Key	initKey_ The key used to initialize this object.
protected iaik.pkcs.pkcs11.objects.Key	initKeyObject_ The PKCS#11 key object used to initialize this object..
protected PKCS11KeyAgreementSpec	keyAgreementSpec_ The parameters for this key agreement.
protected boolean	keyAgreementSpecChanged_ Indicates that the parameters for this key agreement changed.
protected IAIKPKCS11Key	phaseKey_ The key used for the current phase
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.KeyAgreement	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 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

Constructor and Description
PKCS11KeyAgreement() Default constructor.

Method Summary

Modifier and Type	Method and Description
protected abstract void	checkInitKeyObject(iaik.pkcs.pkcs11.objects.Key key) Check the key object used for initialization, if it is acceptable for this agreement implementation.
protected abstract void	checkPhaseKeyObject(iaik.pkcs.pkcs11.objects.Key key) Check the key object used for a phase, if it is acceptable for this agreement implementation.
protected java.security.Key	engineDoPhase(java.security.Key key, boolean lastPhase) Returns the key resulting from the next phase of this key agreement.
protected byte[]	engineGenerateSecret() Returns the shared secret finally generated by this key agreement.
protected int	engineGenerateSecret(byte[] sharedSecret, int offset) Generates the shared secret finishing this key agreement procedure and writes it into the given byte array, beginning at the given offset position.
protected javax.crypto.SecretKey	engineGenerateSecret(java.lang.String algorithm) Returns the shared secret finally generated by this key agreement as SecretKey to be used for the secret key algorithm given by its name.
protected void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this KeyAgreement with the given key, algorithm parameters, and random seed.
protected void	engineInit(java.security.Key key, java.security.SecureRandom random) Initializes this KeyAgreement with the given key and random seed, where the given key constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure.
protected byte[]	extractValue(iaik.pkcs.pkcs11.objects.SecretKey secretKeyObject) Extract the value of the given secret key object and return it as byte array.
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 key agreement algorithm.
protected abstract int	getMaxSecretLength(iaik.pkcs.pkcs11.objects.Key phaseKey) Get the maximum length in bytes of the resulting shared secret key.
protected abstract iaik.pkcs.pkcs11.Mechanism	getMechanism() Get the mechanism that this key agreement uses.
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	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 java.security.Key	pkcs11DoPhase(java.security.Key key, boolean lastPhase) Returns the key resulting from the next phase of this key agreement.
protected byte[]	pkcs11GenerateSecret() Returns the shared secret finally generated by this key agreement.
protected int	pkcs11GenerateSecret(byte[] sharedSecret, int offset) Generates the shared secret finishing this key agreement procedure and writes it into the given byte array, beginning at the given offset position.
protected javax.crypto.SecretKey	pkcs11GenerateSecret(java.lang.String algorithm) Returns the shared secret finally generated by this key agreement as SecretKey to be used for the secret key algorithm given by its name.
protected void	pkcs11Init(java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this KeyAgreement with the given key, algorithm parameters, and random seed.
protected void	pkcs11Init(java.security.Key key, java.security.SecureRandom random) Initializes this KeyAgreement with the given key and random seed, where the given key constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, 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.

keyAgreementSpec_

protected PKCS11KeyAgreementSpec keyAgreementSpec_

The parameters for this key agreement.

keyAgreementSpecChanged_

protected boolean keyAgreementSpecChanged_

Indicates that the parameters for this key agreement changed.

initialized_

protected boolean initialized_

Indicates, if this object is initialized and ready for signing or verification.

pkcs11OperationInitialized_

protected boolean pkcs11OperationInitialized_

Indicates, if the PKCS#11 signature/verify is already initialized for the next operation round.

initKey_

protected IAIKPKCS11Key initKey_

The key used to initialize this object.

initKeyObject_

protected iaik.pkcs.pkcs11.objects.Key initKeyObject_

The PKCS#11 key object used to initialize this object..

phaseKey_

protected IAIKPKCS11Key phaseKey_

The key used for the current phase

currentKeyIsSoftwareKey_

protected boolean currentKeyIsSoftwareKey_

Indicates that the currently used key is a software key.

softwareDelegate_

protected javax.crypto.KeyAgreement 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.

Constructor Detail

PKCS11KeyAgreement

public PKCS11KeyAgreement()

Default constructor.

Method Detail

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)

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 mechanism.

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 support 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)

checkInitKeyObject

protected abstract void checkInitKeyObject(iaik.pkcs.pkcs11.objects.Key key)
                                    throws java.security.InvalidKeyException

Check the key object used for initialization, if it is acceptable for this agreement implementation. Throw an exception, if not.

Parameters:

key - The initialization key object to check.

Throws:

java.security.InvalidKeyException - If this implementation cannot work with this type of key object.

Preconditions:

(key <> null)

checkPhaseKeyObject

protected abstract void checkPhaseKeyObject(iaik.pkcs.pkcs11.objects.Key key)
                                     throws java.security.InvalidKeyException

Check the key object used for a phase, if it is acceptable for this agreement implementation. Throw an exception, if not.

Parameters:

key - The phase key object to check.

Throws:

java.security.InvalidKeyException - If this implementation cannot work with this type of key object.

Preconditions:

(key <> null)

engineInit

protected void engineInit(java.security.Key key,
                          java.security.SecureRandom random)
                   throws java.security.InvalidKeyException

Initializes this KeyAgreement with the given key and random seed, where the given key constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity's private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement). 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.KeyAgreementSpi

Parameters:

key - the private key information of the entity involved in the key agreement

random - the random seed

Throws:

java.security.InvalidKeyException - if the given key cannot be used for this key agreement

initializeSession

protected void initializeSession()

Sets up an appropriate session. The key must be set before.

initializePkcs11Operation

protected void initializePkcs11Operation()

The internal session initialization method, if all necessary member variables are set.

finalizePkcs11Operation

protected void finalizePkcs11Operation()

The internal session finalization method, if the current operation has been finished.

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 key agreement algorithm.

Returns:

The JCA standard name of this agreement algorithm.

Postconditions:

(result <> null)

pkcs11Init

protected void pkcs11Init(java.security.Key key,
                          java.security.SecureRandom random)
                   throws java.security.InvalidKeyException

Initializes this KeyAgreement with the given key and random seed, where the given key constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity's private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Parameters:

key - the private key information of the entity involved in the key agreement

random - the random seed

Throws:

java.security.InvalidKeyException - if the given key cannot be used for this key agreement

engineInit

protected void engineInit(java.security.Key key,
                          java.security.spec.AlgorithmParameterSpec params,
                          java.security.SecureRandom random)
                   throws java.security.InvalidKeyException,
                          java.security.InvalidAlgorithmParameterException

Initializes this KeyAgreement with the given key, algorithm parameters, and random seed. The given key constitutes the private key of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity's private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement). 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.KeyAgreementSpi

Parameters:

key - the private key information of the entity involved in the key agreement

params - The algorithm parameters used for this key agreement algorithm. It must be a PKCS11KeyAgreementSpec for this implementation.

random - The random seed. This implementation ignores this parameter.

Throws:

java.security.InvalidKeyException - if the given key cannot be used for this key agreement

java.security.InvalidAlgorithmParameterException - if the given parameters do not match to this key agreement algorithm

Preconditions:

(key <> null) and (params <> null)

pkcs11Init

protected void pkcs11Init(java.security.Key key,
                          java.security.spec.AlgorithmParameterSpec params,
                          java.security.SecureRandom random)
                   throws java.security.InvalidKeyException,
                          java.security.InvalidAlgorithmParameterException

Initializes this KeyAgreement with the given key, algorithm parameters, and random seed. The given key constitutes the private key of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity's private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Parameters:

key - the private key information of the entity involved in the key agreement

params - The algorithm parameters used for this key agreement algorithm. It must be a PKCS11KeyAgreementSpec for this implementation.

random - The random seed. This implementation ignores this parameter.

Throws:

java.security.InvalidKeyException - if the given key cannot be used for this key agreement

java.security.InvalidAlgorithmParameterException - if the given parameters do not match to this key agreement algorithm

Preconditions:

(key <> null) and (key instanceof IAIKPKCS11Key) and (params <> null) and (params instanceof PKCS11KeyAgreementSpec)

engineDoPhase

protected java.security.Key engineDoPhase(java.security.Key key,
                                          boolean lastPhase)
                                   throws java.security.InvalidKeyException,
                                          java.lang.IllegalStateException

Returns the key resulting from the next phase of this key agreement. This implementation delegates this call to the software provider, if the current base 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:

engineDoPhase in class javax.crypto.KeyAgreementSpi

Parameters:

key - the required key for this phase, supplied by some other entity involved in this key agreement

lastPhase - true if this is the last phase of this key agreement, false if not

Returns:

the key resulting from this phase, or null if no key is returned by this phase

Throws:

java.security.InvalidKeyException - if the given key cannot be used for this key agreement algorithm / phase

java.lang.IllegalStateException - if the given phase cannot be performed in this state of the key agreement procedure

Preconditions:

(key <> null)

pkcs11DoPhase

protected java.security.Key pkcs11DoPhase(java.security.Key key,
                                          boolean lastPhase)
                                   throws java.security.InvalidKeyException,
                                          java.lang.IllegalStateException

Returns the key resulting from the next phase of this key agreement.

Parameters:

key - the required key for this phase, supplied by some other entity involved in this key agreement

lastPhase - true if this is the last phase of this key agreement, false if not

Returns:

the key resulting from this phase, or null if no key is returned by this phase

Throws:

java.security.InvalidKeyException - if the given key cannot be used for this key agreement algorithm / phase

java.lang.IllegalStateException - if the given phase cannot be performed in this state of the key agreement procedure

Preconditions:

(key <> null) and (key instanceof IAIKPKCS11Key)

engineGenerateSecret

protected byte[] engineGenerateSecret()
                               throws java.lang.IllegalStateException

Returns the shared secret finally generated by this key agreement. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again. This implementation delegates this call to the software provider, if the current base 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:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Returns:

The generated shared secret within a byte array or null, if it cannot be extracted from the token.

Throws:

java.lang.IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

pkcs11GenerateSecret

protected byte[] pkcs11GenerateSecret()
                               throws java.lang.IllegalStateException

Returns the shared secret finally generated by this key agreement. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Returns:

The generated shared secret within a byte array or null, if it cannot be extracted from the token.

Throws:

java.lang.IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

engineGenerateSecret

protected int engineGenerateSecret(byte[] sharedSecret,
                                   int offset)
                            throws java.lang.IllegalStateException,
                                   javax.crypto.ShortBufferException

Generates the shared secret finishing this key agreement procedure and writes it into the given byte array, beginning at the given offset position. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again. This implementation delegates this call to the software provider, if the current base 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:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Parameters:

sharedSecret - the byte array to which the generated secret has to be written

offset - the offset indicating the start position within the output byte array to which to write the generated shared secret

Returns:

The number of bytes that are stored in the output byte array or -1, if the key cannot be extracted from the token.

Throws:

java.lang.IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

javax.crypto.ShortBufferException - if the given output buffer is too small for holding the secret

Preconditions:

(sharedSecret <> null)

pkcs11GenerateSecret

protected int pkcs11GenerateSecret(byte[] sharedSecret,
                                   int offset)
                            throws java.lang.IllegalStateException,
                                   javax.crypto.ShortBufferException

Generates the shared secret finishing this key agreement procedure and writes it into the given byte array, beginning at the given offset position. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Parameters:

sharedSecret - the byte array to which the generated secret has to be written

offset - the offset indicating the start position within the output byte array to which to write the generated shared secret

Returns:

The number of bytes that are stored in the output byte array or -1, if the key cannot be extracted from the token.

Throws:

java.lang.IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

javax.crypto.ShortBufferException - if the given output buffer is too small for holding the secret

Preconditions:

(sharedSecret <> null)

engineGenerateSecret

protected javax.crypto.SecretKey engineGenerateSecret(java.lang.String algorithm)
                                               throws java.lang.IllegalStateException,
                                                      java.security.NoSuchAlgorithmException,
                                                      java.security.InvalidKeyException

Returns the shared secret finally generated by this key agreement as SecretKey to be used for the secret key algorithm given by its name. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again. This implementation delegates this call to the software provider, if the current base 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:

engineGenerateSecret in class javax.crypto.KeyAgreementSpi

Parameters:

algorithm - The name of the secret key algorithm for which the generated secret key shall be used. This implementation ignores this parameter.

Returns:

the generated shared secret as SecretKey

Throws:

java.lang.IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

java.security.NoSuchAlgorithmException - if the given secret key algorithm is not supported

java.security.InvalidKeyException - if the generated shared secret cannot be returned as SecretKey matching to the given algorithm

Postconditions:

(result <> null)

pkcs11GenerateSecret

protected javax.crypto.SecretKey pkcs11GenerateSecret(java.lang.String algorithm)
                                               throws java.lang.IllegalStateException,
                                                      java.security.NoSuchAlgorithmException,
                                                      java.security.InvalidKeyException

Returns the shared secret finally generated by this key agreement as SecretKey to be used for the secret key algorithm given by its name. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Parameters:

algorithm - The name of the secret key algorithm for which the generated secret key shall be used. This implementation ignores this parameter.

Returns:

the generated shared secret as SecretKey

Throws:

java.lang.IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

java.security.NoSuchAlgorithmException - if the given secret key algorithm is not supported

java.security.InvalidKeyException - if the generated shared secret cannot be returned as SecretKey matching to the given algorithm

Postconditions:

(result <> null)

extractValue

protected byte[] extractValue(iaik.pkcs.pkcs11.objects.SecretKey secretKeyObject)

Extract the value of the given secret key object and return it as byte array.

Parameters:

secretKeyObject - The pkcs#11 secret key object to get the value.

Returns:

The value bytes of the key object.

Preconditions:

(secretKeyObject <> null)

getMechanism

protected abstract iaik.pkcs.pkcs11.Mechanism getMechanism()

Get the mechanism that this key agreement uses. This must already include any required parameters.

Returns:

The mechanism that this key generator uses.

Postconditions:

(result <> null)

getMaxSecretLength

protected abstract int getMaxSecretLength(iaik.pkcs.pkcs11.objects.Key phaseKey)

Get the maximum length in bytes of the resulting shared secret key. Since this depends on the algorithm, it is abstract and has to be implemented by concrete classes.

The provided phase key may help the implementation in determining the maximum length; e.g. for Diffie-Hellman in getting the length of the prime P.

Parameters:

phaseKey - The (last) phase key which has been passed to engineDoPhase(Key, boolean).

Returns:

The maximum shared secret length in bytes.

Postconditions:

(result > 0)

Preconditions:

(phaseKey <> 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.