iaik.pkcs.pkcs11.me
Class KeyTemplate

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

public class KeyTemplate

extends java.lang.Object

Key templates are for setting new keys in a key store using the KeyStore.setKey(String,KeyTemplate) method.

The application creates a new key template using the KeyTemplate(long, String, long[]) constructor, and sets the individual key material using the setComponent(long, Object) method.

A typical piece of code creating a template for a RSA private key looks like this:

  long[] usages = new long[] {Key.USAGE_SIGNATURE_CREATION};
  KeyTemplate template = new KeyTemplate(Key.TYPE_PRIVATE_KEY, Key.ALGORITHM_RSA, usages);
  template.setComponent(Key.COMPONENT_MODULUS, key.getBigInteger(CryptoBag.V_RSA_N).toByteArray(false));
  template.setComponent(Key.COMPONENT_PRIVATE_EXPONENT, key.getBigInteger(CryptoBag.V_RSA_D).toByteArray(false));
  template.setComponent(Key.COMPONENT_PUBLIC_EXPONENT, key.getBigInteger(CryptoBag.V_RSA_E).toByteArray(false));
  template.setComponent(Key.COMPONENT_PRIME_1, key.getBigInteger(CryptoBag.V_RSA_CRT_P).toByteArray(false));
  template.setComponent(Key.COMPONENT_PRIME_2, key.getBigInteger(CryptoBag.V_RSA_CRT_Q).toByteArray(false));
  template.setComponent(Key.COMPONENT_EXPONENT_1, key.getBigInteger(CryptoBag.V_RSA_CRT_EP).toByteArray(false));
  template.setComponent(Key.COMPONENT_EXPONENT_2, key.getBigInteger(CryptoBag.V_RSA_CRT_EQ).toByteArray(false));
  template.setComponent(Key.COMPONENT_COEFFICIENT, key.getBigInteger(CryptoBag.V_RSA_CRT_C).toByteArray(false));

  String alias = ... // create a alias for the key
  Key key = keyStore.setKey(alias, template);
 

Note that the calls like key.getBigInteger(CryptoBag.V_RSA_N).toByteArray(false) stem from the IAIK JCE Micro Edition. However, its use is not required. Any other code can be used which gets the component value as byte array without a signum bit. Please note that the toByteArray() method of Java always include a signum bit. In this case, the application must remove this leading signum bit if this causes a leading zero byte. Remove the leading zero byte.

See Also:

KeyStore

Constructor Summary

KeyTemplate(long type, java.lang.String algorithm, long[] usages)
Create a new key template.

Method Summary

boolean	canBeUsedFor(long usage) This method determines if this key template is configured for a certain purpose.
java.lang.String	getAlgorithm() Get the algorithm name of this key template.
java.lang.Object	getComponent(long componentType) Get a specific component of this key template; e.g. the modulus of an RSA key, or the value of a secret key.
long	getType() Get the key type.
boolean	isToken() Check if the key template specifies that the object should be stored on the token throughout the session; i.e. if it should be a token object (CKA_TOKEN set to true).
void	setComponent(long componentType, java.lang.Object componentValue) Set a specific component of this key; e.g. the modulus of an RSA key, or the value of a secret key.
void	setToken(boolean value) Set, if the object created by this template should be stored persistently on the token throughout the current session; i.e. if it should be a token object (CKA_TOKEN set to true)

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyTemplate

public KeyTemplate(long type,
                   java.lang.String algorithm,
                   long[] usages)

Create a new key template. The application must specify the key type (private, public or secret), the key algorithm (e.g. RSA) and the allowed key usage.

The key usages must be compatible with the key type. Key.USAGE_SIGNATURE_CREATION and Key.USAGE_DECRYPTION is allowed for private keys and secret keys only. Key.USAGE_SIGNATURE_VERIFICATION and Key.USAGE_ENCRYPTION is allowed for public keys and secret keys only.

Parameters:

type - The key type; i.e. a constant starting with Key.TYPE_.

algorithm - The key algorithm; i.e. a constant starting with Key.ALGORITHM_.

usages - The allowed key usages.

Method Detail

canBeUsedFor

public boolean canBeUsedFor(long usage)

This method determines if this key template is configured for a certain purpose. Valid usage values are all constants in the Key class which start with USAGE_; e.g. Key.USAGE_SIGNATURE_CREATION.

Parameters:

usage - The usage identifier; e.g. Key.USAGE_SIGNATURE_CREATION.

Returns:

true if this key template is configured for this purpose.

getAlgorithm

public java.lang.String getAlgorithm()

Get the algorithm name of this key template.

The known algorithms are all constants of the Key class which start with ALGORITHM_.

Returns:

The name of the key algorithm or null if the key has an unknown algorithm.

getType

public long getType()

Get the key type. This is either Key.TYPE_PRIVATE_KEY, Key.TYPE_PUBLIC_KEY or Key.TYPE_SECRET_KEY.

Returns:

The key type.

getComponent

public java.lang.Object getComponent(long componentType)

Get a specific component of this key template; e.g. the modulus of an RSA key, or the value of a secret key. The component type can be any of the constants starting with COMPONENT_. Primitive values like long values or byte values are returned as their corresponding object types; e.g. java.lang.Long or java.lang.Byte. Arrays are returned as arrays of the primitive type; e.g. byte arrays are returned as byte[] type. Strings are returned as char[] type.

This method will return null if the attribute is present in the template and has the value null.

Parameters:

componentType - The requested component; e.g. COMPONENT_MODULUS for a RSA key.

Returns:

The component value or null if the value is actually null.

setComponent

public void setComponent(long componentType,
                         java.lang.Object componentValue)

Set a specific component of this key; e.g. the modulus of an RSA key, or the value of a secret key. The component type can be any of the constants starting with COMPONENT_. Primitive values like long values or byte values are given as their corresponding object types; e.g. java.lang.Long or java.lang.Byte. Arrays are specified as arrays of the primitive type; e.g. byte arrays are returned as byte[] type. Strings are expected as char[] type.

This method accepts null for the attribute value.

If the key does not possess the specified component or if the specified component is sensitive, this method will throw the checked exception PKCS11Exception. For example, if the application tries to set the COMPONENT_MODULUS component in a DES key.

Parameters:

componentType - The requested component; e.g. COMPONENT_MODULUS for a RSA key.

componentValue - The component value or null.

Throws:

PKCS11Exception - If the key does not possess the requested component or if it is sensitive.

PKCS11RuntimeException - If setting the component failed for some other reason.

setToken

public void setToken(boolean value)

Set, if the object created by this template should be stored persistently on the token throughout the current session; i.e. if it should be a token object (CKA_TOKEN set to true)

Parameters:

value -

isToken

public boolean isToken()

Check if the key template specifies that the object should be stored on the token throughout the session; i.e. if it should be a token object (CKA_TOKEN set to true). If the attribute has not been set, it defaults to true.

Returns:

true if the object should be stored persistently.