iaik.pkcs.pkcs11.provider

Class DefaultKeyHandler

java.lang.Object

iaik.pkcs.pkcs11.provider.Configurable

iaik.pkcs.pkcs11.provider.KeyHandler

iaik.pkcs.pkcs11.provider.DefaultKeyHandler

public class DefaultKeyHandler
extends KeyHandler

This is the default implementation of the KeyHandler interface. It allows automatic transformation of software keys and parameters to corresponding PKCS#11 versions (see setAutoConversion(boolean)).

The automatic conversion imports the given software keys into the underlying PKCS#11 token. Such automatically imported keys always become session objects, and they are deleted automatically when the corresponding IAIKPKCS11Key object gets finalized (see IAIKPKCS11Key.setAutoDestroy(boolean)).
All private keys and secret keys are marked as sensitive and private objects in the PKCS#11 token.

Author:

Karl Scheibelhofer

Field Summary

Fields inherited from class iaik.pkcs.pkcs11.provider.Configurable

defaultProperties_, properties_

Constructor Summary

Constructors

Constructor and Description
DefaultKeyHandler() Default constructor.

Method Summary

Modifier and Type	Method and Description
iaik.pkcs.pkcs11.objects.SecretKey	getKeyGeneratorTemplate(java.lang.String algorithm, java.security.spec.AlgorithmParameterSpec params) Get a secret key template object for the given key generation algorithm.
iaik.pkcs.pkcs11.objects.SecretKey	getKeyGeneratorTemplate(java.lang.String algorithm, int keySize) Get a secret key template object for the given key generation algorithm.
iaik.pkcs.pkcs11.objects.KeyPair	getKeyPairGeneratorTemplate(java.lang.String algorithm, java.security.spec.AlgorithmParameterSpec params) Get a private and a public key template object for the given key-pair generation algorithm.
iaik.pkcs.pkcs11.objects.KeyPair	getKeyPairGeneratorTemplate(java.lang.String algorithm, int keySize) Get a private and a public key template object for the given key-pair generation algorithm.
java.security.Key	handleCipherKey(java.lang.String algorithm, int operationMode, java.security.Key key) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
java.security.Key	handleKeyAgreementKey(java.lang.String algorithm, java.security.Key key, java.security.spec.AlgorithmParameterSpec params) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
java.security.Key	handleKeyAgreementPhaseKey(java.lang.String algorithm, java.security.Key key) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
java.security.spec.KeySpec	handleKeyFactoryGeneratePrivate(java.lang.String algorithm, java.security.spec.KeySpec keySpec) If auto conversion is switched on and the given key spec is not a PKCS11KeySpec, this implementation converts the key spec to a PKCS11KeySpec object.
java.security.spec.KeySpec	handleKeyFactoryGeneratePublic(java.lang.String algorithm, java.security.spec.KeySpec keySpec) If auto conversion is switched on and the given key spec is not a PKCS11KeySpec, this implementation converts the key spec to a PKCS11KeySpec object.
java.security.Key	handleKeyFactoryTranslateKey(java.lang.String algorithm, java.security.Key key) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
java.security.Key	handleMacKey(java.lang.String algorithm, java.security.Key key) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
java.security.spec.KeySpec	handleSecretKeyFactoryGenerateSecret(java.lang.String algorithm, java.security.spec.KeySpec keySpec) If auto conversion is switched on and the given key spec is not a PKCS11KeySpec, this implementation converts the key spec to a PKCS11KeySpec object.
javax.crypto.SecretKey	handleSecretKeyFactoryTranslateKey(java.lang.String algorithm, javax.crypto.SecretKey key) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
java.security.PrivateKey	handleSignatureKey(java.lang.String algorithm, java.security.PrivateKey key) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
java.security.PublicKey	handleVerificationKey(java.lang.String algorithm, java.security.PublicKey key) If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
boolean	isAutoConversion()
protected void	propertiesChanged() Read properties.
void	setAutoConversion(boolean on) Switch the automatic conversion feature on or off.

Methods inherited from class iaik.pkcs.pkcs11.provider.Configurable

addProperties, getProperties, setProperties

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultKeyHandler

public DefaultKeyHandler()

Default constructor. This is used for instantiation by name.

Method Detail

propertiesChanged

protected void propertiesChanged()

Read properties.

Overrides:

propertiesChanged in class Configurable

handleCipherKey

public java.security.Key handleCipherKey(java.lang.String algorithm,
                                         int operationMode,
                                         java.security.Key key)
                                  throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

During conversion, this method will set the encrypt, decrypt, wrap or unwrap flags of the PKCS#11 object denpending on the specified operationMode.

Specified by:

handleCipherKey in class KeyHandler

Parameters:

algorithm - The JCE name of the cipher algorithm; e.g. RSA or DESede. Note that this is not the complete transformation string like DESese/CBC/PKCS5Padding.

operationMode - The mode as passed to the cipher's init method; e.g. Cipher.ENCRYPT_MODE.

key - The key.

Returns:

The handled key.

Throws:

java.security.InvalidKeyException - If the given key is invalid for this algorithm or mode.

See Also:

isAutoConversion()

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

handleMacKey

public java.security.Key handleMacKey(java.lang.String algorithm,
                                      java.security.Key key)
                               throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

During conversion, this method will set the sign flag of the PKCS#11 object.

Specified by:

handleMacKey in class KeyHandler

Parameters:

algorithm - The JCE name of the MAC algorithm; e.g. HmacSHA1.

key - The key.

Returns:

The handled key.

Throws:

java.security.InvalidKeyException - If the given key is invalid for this algorithm.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

handleSignatureKey

public java.security.PrivateKey handleSignatureKey(java.lang.String algorithm,
                                                   java.security.PrivateKey key)
                                            throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

During conversion, this method will set the sign flag of the PKCS#11 object.

Specified by:

handleSignatureKey in class KeyHandler

Parameters:

algorithm - The JCA name of the signature algorithm; e.g. SHA1withRSA.

key - The signature key.

Returns:

The handled key.

Throws:

java.security.InvalidKeyException - If the given key is invalid for this algorithm or mode.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

handleVerificationKey

public java.security.PublicKey handleVerificationKey(java.lang.String algorithm,
                                                     java.security.PublicKey key)
                                              throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

During conversion, this method will set the verify flag of the PKCS#11 object.

Specified by:

handleVerificationKey in class KeyHandler

Parameters:

algorithm - The JCA name of the signature algorithm; e.g. SHA1withRSA.

key - The verification key.

Returns:

The handled key.

Throws:

java.security.InvalidKeyException - If the given key is invalid for this algorithm or mode.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

handleKeyAgreementKey

public java.security.Key handleKeyAgreementKey(java.lang.String algorithm,
                                               java.security.Key key,
                                               java.security.spec.AlgorithmParameterSpec params)
                                        throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

During conversion, this method will set the derive flag of the PKCS#11 object.

Specified by:

handleKeyAgreementKey in class KeyHandler

Parameters:

algorithm - The JCE name of the key agreement algorithm; e.g. DH.

key - The private key for key agreement.

params - The algorithm parameters passed to the init metod of the key agreement object.

Returns:

The handled private key.

Throws:

java.security.InvalidKeyException - If the given key is invalid for this algorithm or mode.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

handleKeyAgreementPhaseKey

public java.security.Key handleKeyAgreementPhaseKey(java.lang.String algorithm,
                                                    java.security.Key key)
                                             throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

During conversion, this method will set the derive flag of the PKCS#11 object.

Specified by:

handleKeyAgreementPhaseKey in class KeyHandler

Parameters:

algorithm - The JCE name of the key agreement algorithm; e.g. DH.

key - The public phase key.

Returns:

The handled public phase key.

Throws:

java.security.InvalidKeyException - If the given key is invalid for this algorithm or mode.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

handleKeyFactoryGeneratePublic

public java.security.spec.KeySpec handleKeyFactoryGeneratePublic(java.lang.String algorithm,
                                                                 java.security.spec.KeySpec keySpec)
                                                          throws java.security.spec.InvalidKeySpecException

If auto conversion is switched on and the given key spec is not a PKCS11KeySpec, this implementation converts the key spec to a PKCS11KeySpec object. This new key spec will result in a session key with the default crypto operation flags.

Otherwise, this method returns the key spec without touching it.

Specified by:

handleKeyFactoryGeneratePublic in class KeyHandler

Parameters:

algorithm - The algorithm name of the key factory; e.g. RSA.

keySpec - The key spec which the application passed to the generatePublic(KeySpec) method of the key factory.

Returns:

The handled key spec. This may be the original object which has been provided as keySpec object.

Throws:

java.security.spec.InvalidKeySpecException - If the given key spec is invalid in this context.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (keySpec <> null)

handleKeyFactoryGeneratePrivate

public java.security.spec.KeySpec handleKeyFactoryGeneratePrivate(java.lang.String algorithm,
                                                                  java.security.spec.KeySpec keySpec)
                                                           throws java.security.spec.InvalidKeySpecException

If auto conversion is switched on and the given key spec is not a PKCS11KeySpec, this implementation converts the key spec to a PKCS11KeySpec object. This new key spec will result in a session key with the default crypto operation flags.

Otherwise, this method returns the key spec without touching it.

Specified by:

handleKeyFactoryGeneratePrivate in class KeyHandler

Parameters:

algorithm - The algorithm name of the key factory; e.g. RSA.

keySpec - The key spec which the application passed to the generatePrivate(KeySpec) method of the key factory.

Returns:

The handled key spec. This may be the original object which has been provided as keySpec object.

Throws:

java.security.spec.InvalidKeySpecException - If the given key spec is invalid in this context.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (keySpec <> null)

handleKeyFactoryTranslateKey

public java.security.Key handleKeyFactoryTranslateKey(java.lang.String algorithm,
                                                      java.security.Key key)
                                               throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

Specified by:

handleKeyFactoryTranslateKey in class KeyHandler

Parameters:

algorithm - The algorithm name of the key factory; e.g. RSA.

key - The key which the application passed to the translateKey(Key) method of the key factory.

Returns:

The handled key. This may be the original object which has been provided as key argument.

Throws:

java.security.InvalidKeyException - If the given key is invalid in this context.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

handleSecretKeyFactoryGenerateSecret

public java.security.spec.KeySpec handleSecretKeyFactoryGenerateSecret(java.lang.String algorithm,
                                                                       java.security.spec.KeySpec keySpec)
                                                                throws java.security.spec.InvalidKeySpecException

If auto conversion is switched on and the given key spec is not a PKCS11KeySpec, this implementation converts the key spec to a PKCS11KeySpec object. This new key spec will result in a session key with the default crypto operation flags.

Otherwise, this method returns the key spec without touching it.

Specified by:

handleSecretKeyFactoryGenerateSecret in class KeyHandler

Parameters:

algorithm - The algorithm name of the key factory; e.g. DESede or AES.

keySpec - The key spec which the application passed to the generateSecret(KeySpec) method of the secret key factory.

Returns:

The handled key spec. This may be the original object which has been provided as keySpec argument.

Throws:

java.security.spec.InvalidKeySpecException - If the given key spec is invalid in this context.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (keySpec <> null)

handleSecretKeyFactoryTranslateKey

public javax.crypto.SecretKey handleSecretKeyFactoryTranslateKey(java.lang.String algorithm,
                                                                 javax.crypto.SecretKey key)
                                                          throws java.security.InvalidKeyException

If auto conversion is switched on and the given key is not a key of this provider, this implementation converts the key to a PKCS#11 key.
Otherwise, this method returns the key without touching it.

Specified by:

handleSecretKeyFactoryTranslateKey in class KeyHandler

Parameters:

algorithm - The algorithm name of the key factory; e.g. DESede or AES.

key - The key which the application passed to the translateKey(SecretKey) method of the secret key factory.

Returns:

The handled key. This may be the original object which has been provided as key argument.

Throws:

java.security.InvalidKeyException - If the given key is invalid in this context.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (key <> null)

getKeyPairGeneratorTemplate

public iaik.pkcs.pkcs11.objects.KeyPair getKeyPairGeneratorTemplate(java.lang.String algorithm,
                                                                    int keySize)
                                                             throws java.security.InvalidParameterException

Get a private and a public key template object for the given key-pair generation algorithm.

Specified by:

getKeyPairGeneratorTemplate in class KeyHandler

Parameters:

algorithm - The key-pair generation algorithm; e.g. RSA.

keySize - The key size in bits; e.g. 1024.

Returns:

The key-pair template.

Throws:

java.security.InvalidParameterException - If the key size is invalid.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (keySize > 0)

getKeyPairGeneratorTemplate

public iaik.pkcs.pkcs11.objects.KeyPair getKeyPairGeneratorTemplate(java.lang.String algorithm,
                                                                    java.security.spec.AlgorithmParameterSpec params)
                                                             throws java.security.InvalidAlgorithmParameterException

Get a private and a public key template object for the given key-pair generation algorithm.

This method only gets parameters which are not of type PKCS11KeyPairGenerationSpec.

The key-pair generators handle such parameter directly. For example, they will get the values from the parameters object enclosed by the PKCS11KeyPairGenerationSpec object and put the values into the key template. For instance, if the application provides a PKCS11KeyPairGenerationSpec object with an enclosed javax.crypto.spec.DHParameterSpec object to a DH key-pair generator, the generator will itself put the P and G value into the public key template and the L value into the private key template.

Specified by:

getKeyPairGeneratorTemplate in class KeyHandler

Parameters:

algorithm - The key-pair generation algorithm; e.g. RSA.

params - The algorithm parameters; e.g. javax.crypto.spec.DHParameterSpec.

Returns:

The key-pair template.

Throws:

java.security.InvalidAlgorithmParameterException - If the parameters are invalid for this algorithm.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (params <> null)

getKeyGeneratorTemplate

public iaik.pkcs.pkcs11.objects.SecretKey getKeyGeneratorTemplate(java.lang.String algorithm,
                                                                  int keySize)
                                                           throws java.security.InvalidParameterException

Get a secret key template object for the given key generation algorithm.

Specified by:

getKeyGeneratorTemplate in class KeyHandler

Parameters:

algorithm - The key generation algorithm; e.g. AES.

keySize - The key size in bits; e.g. 128. Use -1 to use the default key size.

Returns:

The key template.

Throws:

java.security.InvalidParameterException - If the key size is invalid.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and ((keySize == -1) or (keySize > 0))

getKeyGeneratorTemplate

public iaik.pkcs.pkcs11.objects.SecretKey getKeyGeneratorTemplate(java.lang.String algorithm,
                                                                  java.security.spec.AlgorithmParameterSpec params)
                                                           throws java.security.InvalidAlgorithmParameterException

Get a secret key template object for the given key generation algorithm.

This method only gets parameters which are not of type PKCS11KeyGenerationSpec.

The key generators handle such parameter directly. For example, they will get the values from the parameters object enclosed by the PKCS11KeyGenerationSpec object and put the values into the key template.

Specified by:

getKeyGeneratorTemplate in class KeyHandler

Parameters:

algorithm - The key generation algorithm; e.g. AES.

params - The algorithm parameters>.

Returns:

The key template.

Throws:

java.security.InvalidAlgorithmParameterException - If the parameters are invalid for this algorithm.

Postconditions:

(result <> null)

Preconditions:

(algorithm <> null) and (params <> null)

setAutoConversion

public void setAutoConversion(boolean on)

Switch the automatic conversion feature on or off.

Parameters:

on - true, to switch it on.

isAutoConversion

public boolean isAutoConversion()

Returns:

true, if automatic conversion is switched on.