iaik.pkcs.pkcs11.me
Class KeyGenerator

java.lang.Object
  iaik.pkcs.pkcs11.me.KeyGenerator

public class KeyGenerator

extends java.lang.Object

A KeyGenerator object can generate keys directly on the associated token. For example, such on object can generate a new 128 bit AES key on the token.

First, the application has to initialize the key generator by calling init(int, int, String, boolean). After this has been done, it can invoke generateKey() to trigger the key generation.

A typical piece of code which uses the key generator may look like this:

  Token token = ... // get token from module
  KeyGenerator keyGenerator = token.getKeyGenerator(KeyGenerator.ALGORITHM_AES);
 
  String label = ... // assign some label, should not conflict with an alias of the key store
 
  // note the last parameter "false" which means that this key is only valid for this session
  keyPairGenerator.initialize(1024, KeyPairGenerator.USAGE_SIGNATURE, label, false);
 
  Key key = keyGenerator.generateKey();
 
  ... // use the key
 
  // we can explicitly release the session, this frees up resources and deletes the key
  key.releaseSession();
 

The label can be used later on to refer to the key in the key store. Therefore, the application should ensure that no alias already exists with such a name. Remind to call KeyStore.update() to see any newly generated keys in the key store.

If the generated key is a session key (i.e. tokenObject parameter for init(int, int, String, boolean) has been set to false), its session should be explicitly released by the application using the key's Key.releaseSession() method when the key is no longer used.

Field Summary

static long	ALGORITHM_AES Algorithm identifier for AES keys.
static long	ALGORITHM_DES Algorithm identifier for DES keys.
static long	ALGORITHM_DESEDE Algorithm identifier for Triple DES keys.
static long	ALGORITHM_GENERIC Algorithm identifier for generic symmetric keys.
static long	ALGORITHM_IDEA Algorithm identifier for IDEA keys.
static long	ALGORITHM_RC2 Algorithm identifier for RC2 keys.
static long	ALGORITHM_RC4 Algorithm identifier for RC4 keys.
static int	USAGE_CIPHER Denotes that the key is for encipherment.
static int	USAGE_SIGNATURE Denotes that the key is for signatures (MACs).
static int	USAGE_WRAP Denotes that the key is for key-wrapping.

Method Summary

Key	generateKey() Generates a key using the parameters given at the init(int, int, String, boolean) call.
void	init(int size, int keyUsage, java.lang.String label, boolean tokenObject) Initialize this key generator for a specific key size, key usage and label for the key.

Methods inherited from class java.lang.Object

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

Field Detail

ALGORITHM_AES

public static final long ALGORITHM_AES

Algorithm identifier for AES keys.

See Also:

Constant Field Values

ALGORITHM_DES

public static final long ALGORITHM_DES

Algorithm identifier for DES keys.

See Also:

Constant Field Values

ALGORITHM_DESEDE

public static final long ALGORITHM_DESEDE

Algorithm identifier for Triple DES keys.

See Also:

Constant Field Values

ALGORITHM_IDEA

public static final long ALGORITHM_IDEA

Algorithm identifier for IDEA keys.

See Also:

Constant Field Values

ALGORITHM_RC2

public static final long ALGORITHM_RC2

Algorithm identifier for RC2 keys.

See Also:

Constant Field Values

ALGORITHM_RC4

public static final long ALGORITHM_RC4

Algorithm identifier for RC4 keys.

See Also:

Constant Field Values

ALGORITHM_GENERIC

public static final long ALGORITHM_GENERIC

Algorithm identifier for generic symmetric keys.

See Also:

Constant Field Values

USAGE_SIGNATURE

public static final int USAGE_SIGNATURE

Denotes that the key is for signatures (MACs).

See Also:

Constant Field Values

USAGE_CIPHER

public static final int USAGE_CIPHER

Denotes that the key is for encipherment.

See Also:

Constant Field Values

USAGE_WRAP

public static final int USAGE_WRAP

Denotes that the key is for key-wrapping.

See Also:

Constant Field Values

Method Detail

init

public void init(int size,
                 int keyUsage,
                 java.lang.String label,
                 boolean tokenObject)
          throws PKCS11RuntimeException

Initialize this key generator for a specific key size, key usage and label for the key.

The key size is specified in bits.

The label will become the key's alias for the key store if it results in a unique alias.

The keyUsage will determine the allowed key usage of the resulting key. If USAGE_SIGNATURE is set, the key will be valid for Key.USAGE_SIGNATURE_CREATION and Key.USAGE_SIGNATURE_VERIFICATION. If USAGE_CIPHER is set, the key will be valid for Key.USAGE_DECRYPTION and Key.USAGE_ENCRYPTION. If USAGE_WRAP is set, the key will be valid for Key.USAGE_WRAP and Key.USAGE_UNWRAP. If USAGE_SIGNATURE + USAGE_CIPHER + USAGE_WRAP is specified, the key will be valid for all these usages. Other combinations are also possible.

If the tokenObject has been set to false), the resulting key's session should be explicitly released by the application using the key's Key.releaseSession() method when the key is no longer used.

Parameters:

size - The key size in bits; e.g. 128 for a 128 bit AES key.

keyUsage - USAGE_SIGNATURE, USAGE_CIPHER, USAGE_WRAP, or any sum of these; e.g. USAGE_SIGNATURE + USAGE_CIPHER or USAGE_CIPHER + USAGE_WRAP.

label - The label of the new key. May be null.

tokenObject - true if the key shall be stored permanently on the token. If false it will be only valid for the current session.

Throws:

PKCS11RuntimeException - If the initialization fails.

generateKey

public Key generateKey()
                throws PKCS11RuntimeException

Generates a key using the parameters given at the init(int, int, String, boolean) call.

The application must call init(int, int, String, boolean) before calling this method.

If the generated key is a session key (i.e. tokenObject parameter for init(int, int, String, boolean) has been set to false), its session should be explicitly released by the application using the key's Key.releaseSession() method when the key is no longer used.

Returns:

The generated key.

Throws:

PKCS11RuntimeException - If key generation fails.

See Also:

init(int, int, String, boolean)