iaik.pkcs.pkcs11.provider

Class KeyHandler

java.lang.Object

iaik.pkcs.pkcs11.provider.Configurable

iaik.pkcs.pkcs11.provider.KeyHandler

Direct Known Subclasses:

DefaultKeyHandler

public abstract class KeyHandler
extends Configurable

This is the interface to the key handler. The application can set its own key handler for the PKCS#11 provider via the IAIKPkcs11.setGlobalKeyHandler(KeyHandler) method.

All cipher, MAC and signature engines of this provider call this method of the current key handler in their init methods; e.g. the javax.crypto.Cipher.init(int,Key) method. This method is called with the original key passed to the init method. The engine object will continue processing with the returned key and will not use the original key any longer.

This allows the key handler to convert the provided key automatically before the PKCS#11 provider starts working with them. For example, a key handler can convert pure software keys of the JCA and JCE framework to PKCS#11 key objects automatically. Such automatic conversion can be especially useful when the PKCS#11 provider is used in conbination with old software or with software which is not aware of any crypto hardware features. This allows simple integration of crpyto accelleration. Please note that this feature will not increase the overall security of the system. The operations are done in the crypto hardware, but the keys still come through the software.

A key handler may decide not to modify the keys and return the provided keys as they are.

Author:

Karl Scheibelhofer

See Also:

DefaultKeyHandler

Field Summary

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

defaultProperties_, properties_

Constructor Summary

Constructors

Constructor and Description
KeyHandler()

Method Summary

Modifier and Type	Method and Description
abstract 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.
abstract iaik.pkcs.pkcs11.objects.SecretKey	getKeyGeneratorTemplate(java.lang.String algorithm, int keySize) Get a secret key template object for the given key generation algorithm.
abstract 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.
abstract 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.
abstract java.security.Key	handleCipherKey(java.lang.String algorithm, int operationMode, java.security.Key key) All cipher engines of this provider call this method of the current key handler in their init methods; e.g.
abstract java.security.Key	handleKeyAgreementKey(java.lang.String algorithm, java.security.Key key, java.security.spec.AlgorithmParameterSpec params) Handle the initial key which has been passed to the init method of a key-agreement object.
abstract java.security.Key	handleKeyAgreementPhaseKey(java.lang.String algorithm, java.security.Key key) Handle the a phase key which has been passed to the doPhase method of a key-agreement object.
abstract java.security.spec.KeySpec	handleKeyFactoryGeneratePrivate(java.lang.String algorithm, java.security.spec.KeySpec keySpec) Key factories (for private and public keys) of this provider call this method of the current key handler.
abstract java.security.spec.KeySpec	handleKeyFactoryGeneratePublic(java.lang.String algorithm, java.security.spec.KeySpec keySpec) Key factories (for private and public keys) of this provider call this method of the current key handler.
abstract java.security.Key	handleKeyFactoryTranslateKey(java.lang.String algorithm, java.security.Key key) Key factories (for private and public keys) of this provider call this method of the current key handler.
abstract java.security.Key	handleMacKey(java.lang.String algorithm, java.security.Key key) All MAC engines of this provider call this method of the current key handler in their init methods; e.g.
abstract java.security.spec.KeySpec	handleSecretKeyFactoryGenerateSecret(java.lang.String algorithm, java.security.spec.KeySpec keySpec) Secret key factories of this provider call this method of the current key handler.
abstract javax.crypto.SecretKey	handleSecretKeyFactoryTranslateKey(java.lang.String algorithm, javax.crypto.SecretKey key) Secret key factories of this provider call this method of the current key handler.
abstract java.security.PrivateKey	handleSignatureKey(java.lang.String algorithm, java.security.PrivateKey key) All signature engines of this provider call this method of the current key handler in their initSign methods; e.g.
abstract java.security.PublicKey	handleVerificationKey(java.lang.String algorithm, java.security.PublicKey key) All signature engines of this provider call this method of the current key handler in their initVerify methods; e.g.

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

addProperties, getProperties, propertiesChanged, setProperties

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyHandler

public KeyHandler()

Method Detail

handleCipherKey

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

All cipher engines of this provider call this method of the current key handler in their init methods; e.g. the javax.crypto.Cipher.init(int,Key) method. This method is called with the original key passed to the init method. The engine object will continue processing with the returned key and will not use the original key any longer.

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.

Postconditions:

(result <> null)

Preconditions:

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

handleMacKey

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

All MAC engines of this provider call this method of the current key handler in their init methods; e.g. the javax.crypto.Mac.init(Key) method. This method is called with the original key passed to the init method. The engine object will continue processing with the returned key and will not use the original key any longer.

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 abstract java.security.PrivateKey handleSignatureKey(java.lang.String algorithm,
                                                            java.security.PrivateKey key)
                                                     throws java.security.InvalidKeyException

All signature engines of this provider call this method of the current key handler in their initSign methods; e.g. the java.security.Signature.initSign(PrivateKey) method. This method is called with the original key passed to the initSign method. The engine object will continue processing with the returned key and will not use the original key any longer.

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 abstract java.security.PublicKey handleVerificationKey(java.lang.String algorithm,
                                                              java.security.PublicKey key)
                                                       throws java.security.InvalidKeyException

All signature engines of this provider call this method of the current key handler in their initVerify methods; e.g. the java.security.Signature.initVerify(PublicKey) method. This method is called with the original key passed to the initVerify method. The engine object will continue processing with the returned key and will not use the original key any longer.

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 abstract java.security.Key handleKeyAgreementKey(java.lang.String algorithm,
                                                        java.security.Key key,
                                                        java.security.spec.AlgorithmParameterSpec params)
                                                 throws java.security.InvalidKeyException

Handle the initial key which has been passed to the init method of a key-agreement object. This is the private key.

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 abstract java.security.Key handleKeyAgreementPhaseKey(java.lang.String algorithm,
                                                             java.security.Key key)
                                                      throws java.security.InvalidKeyException

Handle the a phase key which has been passed to the doPhase method of a key-agreement object. This is a public key of a party involved in the key agreement.

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 abstract java.security.spec.KeySpec handleKeyFactoryGeneratePublic(java.lang.String algorithm,
                                                                          java.security.spec.KeySpec keySpec)
                                                                   throws java.security.spec.InvalidKeySpecException

Key factories (for private and public keys) of this provider call this method of the current key handler. They invoke this method at the beginning in their generatePublic(KeySpec) method implementation. The factory proceeds with the KeySpec returned by this method. It does not use the original any longer.

This allows the key handler to translate the given key spec into a PKCS11KeySpec for a default provider instance.

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

handleKeyFactoryGeneratePrivate

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

Key factories (for private and public keys) of this provider call this method of the current key handler. They invoke this method at the beginning in their generatePrivate(KeySpec) method implementation. The factory proceeds with the KeySpec returned by this method. It does not use the original any longer.

This allows the key handler to translate the given key spec into a PKCS11KeySpec for a default provider instance.

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

handleKeyFactoryTranslateKey

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

Key factories (for private and public keys) of this provider call this method of the current key handler. They invoke this method at the beginning in their translateKey(Key) method implementation. The factory proceeds with the Key returned by this method. It does not use the original any longer.

This allows the key handler to translate the given key into a IAIKPKCS11Key for a default provider instance.

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 abstract java.security.spec.KeySpec handleSecretKeyFactoryGenerateSecret(java.lang.String algorithm,
                                                                                java.security.spec.KeySpec keySpec)
                                                                         throws java.security.spec.InvalidKeySpecException

Secret key factories of this provider call this method of the current key handler. They invoke this method at the beginning in their generateSecret(KeySpec) method implementation. The factory proceeds with the KeySpec returned by this method. It does not use the original any longer.

This allows the key handler to translate the given key spec into a PKCS11KeySpec for a default provider instance.

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 abstract javax.crypto.SecretKey handleSecretKeyFactoryTranslateKey(java.lang.String algorithm,
                                                                          javax.crypto.SecretKey key)
                                                                   throws java.security.InvalidKeyException

Secret key factories of this provider call this method of the current key handler. They invoke this method at the beginning in their translateKey(SecretKey) method implementation. The factory proceeds with the Key returned by this method. It does not use the original any longer.

This allows the key handler to translate the given key into a IAIKPKCS11Key for a default provider instance.

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

Parameters:

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

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

Returns:

The key-pair template.

Throws:

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

Postconditions:

(result <> null)

Preconditions:

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

getKeyPairGeneratorTemplate

public abstract 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.

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

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

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)