IAIK PKCS#11 Provider API Documentation
version 1.6

iaik.pkcs.pkcs11.provider
Class DefaultKeyHandler

java.lang.Object
  extended by iaik.pkcs.pkcs11.provider.Configurable
      extended by iaik.pkcs.pkcs11.provider.KeyHandler
          extended by 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

Constructor Summary
DefaultKeyHandler()
          Default constructor.
 
Method Summary
 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()
           
 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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DefaultKeyHandler

public DefaultKeyHandler()
Default constructor. This is used for instantiation by name.

Method Detail

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()
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (keySpec <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (keySpec <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (keySpec <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (key <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and (keySize > 0)
Postconditions
(result <> null)

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.
Preconditions
(algorithm <> null) and (params <> null)
Postconditions
(result <> 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.
Preconditions
(algorithm <> null) and ((keySize == -1) or (keySize > 0))
Postconditions
(result <> null)

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.
Preconditions
(algorithm <> null) and (params <> null)
Postconditions
(result <> 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.

IAIK PKCS#11 Provider API Documentation
version 1.6

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

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2004, IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved.
version 1.6