iaik.pkcs.pkcs11.me
Class KeyPairGenerator

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

public class KeyPairGenerator

extends java.lang.Object

A KeyPairGenerator object can generate key-pairs directly on the associated token. For example, such on object can generate a new 1024 bit RSA key-pair on the token.

First, the application has to initialize the key-pair generator by calling initialize(int, int, String). After this has been done, it can invoke generateKeyPair() to trigger the key-pair generation. Note that the generation of a key-pair may take a noticeable time. This may even take some minutes on certain tokens.

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

  Token token = ... // get token from module
  KeyPairGenerator keyPairGenerator = token.getKeyPairGenerator(KeyPairGenerator.ALGORITHM_RSA);
 
  String label = ... // assign some label, should not conflict with an alias of the key store
  keyPairGenerator.initialize(1024, KeyPairGenerator.USAGE_SIGNATURE, label);
 
  Key[] keyPair = keyPairGenerator.generateKeyPair();
  Key publicKey = keyPair[0];
  Key privateKey = keyPair[1];
 

The label can be used later on to refer to the private 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. The public key may only be a session key which means that it may not be stored permanently on the token. Thus, the application should store the returned public key.

Field Summary

static long	ALGORITHM_RSA The algorithm code constant for RSA key-pairs according to PKCS#1 version 1.5.
static int	USAGE_CIPHER Denotes that the key-pair is for encipherment.
static int	USAGE_SIGNATURE Denotes that the key-pair is for signatures.
static int	USAGE_WRAP Denotes that the key-pair is for key-wrapping.

Method Summary

Key[]	generateKeyPair() Generates a key-pair using the parameters given at the initialize(int, int, String) call.
void	initialize(int size, int keyUsage, java.lang.String label) Initialize this key-pair 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_RSA

public static final long ALGORITHM_RSA

The algorithm code constant for RSA key-pairs according to PKCS#1 version 1.5.
This corresponds to RSA in the JCA.

See Also:

Constant Field Values

USAGE_SIGNATURE

public static final int USAGE_SIGNATURE

Denotes that the key-pair is for signatures.

See Also:

Constant Field Values

USAGE_CIPHER

public static final int USAGE_CIPHER

Denotes that the key-pair is for encipherment.

See Also:

Constant Field Values

USAGE_WRAP

public static final int USAGE_WRAP

Denotes that the key-pair is for key-wrapping.

See Also:

Constant Field Values

Method Detail

initialize

public void initialize(int size,
                       int keyUsage,
                       java.lang.String label)
                throws PKCS11RuntimeException

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

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

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

Parameters:

size - The key size in bits; e.g. a modulus length of 1024 bits.

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

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

Throws:

PKCS11RuntimeException - If the initialization fails.

generateKeyPair

public Key[] generateKeyPair()
                      throws PKCS11RuntimeException

Generates a key-pair using the parameters given at the initialize(int, int, String) call.

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

Returns:

The generated key-pair. The public key is at index 0, the private key at index 1.

Throws:

PKCS11RuntimeException - If key-pair generation fails.

See Also:

initialize(int, int, String)