Key (IAIK PKCS#11 Provider Micro Edition API Documentation)

Package

Class

Use

Tree

Deprecated

Index

Help

IAIK PKCS#11 Provider Micro Edition
version 1.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

iaik.pkcs.pkcs11.me
Class Key

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

public class Key
extends java.lang.Object

Keys of this class represent keys on the associated token. Such keys can be used with Signature and Cipher object of the same token. It is impossible to use keys of one token with algorithms of another token.

Basically, a key can be a (asymmetric) private key, a public key or a (symmetric) secret key. This is called the key type. The constants starting with TYPE_ are used to identify the type. Use getType() to get the key's type.

In addition, keys have flags indicating their allowed usage; e.g. a private key can be valid for signature creation but not for decryption. The application can call canBeUsedFor(long) to check if a certain usage is allowed.

  Key key = ...
  if (key.canBeUsedFor(Key.USAGE_SIGNATURE_CREATION)) {
    ... // create a signature
  }

Notice that private keys may only be allowed for signature creation and decryption. Public keys may only be used for signature verification and encryption. Secrete keys may be used for either of these purposes. One key may even have more than one allowed key usage; e.g. a private key may be valid for signature creation as well as for decryption.

This class also supports getting the key material from such a token key. This is especially useful if the token generates keys which must be exported from the token. For instance, the public key of a RSA key-pair. Usually, the application must export the public key to apply for a certificate at a CA service. getComponent(long) can be used to get a component of a key.

Field Summary
`static java.lang.String`	`ALGORITHM_AES` Algorithm identifier for AES keys.
`static java.lang.String`	`ALGORITHM_DES` Algorithm identifier for DES keys.
`static java.lang.String`	`ALGORITHM_DESEDE` Algorithm identifier for Triple DES keys.
`static java.lang.String`	`ALGORITHM_DH` Algorithm identifier for Diffie-Hellman keys.
`static java.lang.String`	`ALGORITHM_DSA` Algorithm identifier for DSA keys.
`static java.lang.String`	`ALGORITHM_EC` Algorithm identifier for elliptic curve keys.
`static java.lang.String`	`ALGORITHM_ECDSA` Algorithm identifier for elliptic curve DSA keys.
`static java.lang.String`	`ALGORITHM_GENERIC` Algorithm identifier for generic symmetric keys.
`static java.lang.String`	`ALGORITHM_IDEA` Algorithm identifier for IDEA keys.
`static java.lang.String`	`ALGORITHM_RC2` Algorithm identifier for RC2 keys.
`static java.lang.String`	`ALGORITHM_RC4` Algorithm identifier for RC4 keys.
`static java.lang.String`	`ALGORITHM_RSA` Algorithm identifier for RSA keys.
`static long`	`COMPONENT_COEFFICIENT` Component identifier for the CRT coefficient component of private RSA CRT keys.
`static long`	`COMPONENT_EXPONENT_1` Component identifier for the prime exponent 1 component of private RSA CRT keys.
`static long`	`COMPONENT_EXPONENT_2` Component identifier for the prime exponent 2 component of private RSA CRT keys.
`static long`	`COMPONENT_MODULUS` Component identifier for the modulus component of RSA keys.
`static long`	`COMPONENT_PRIME_1` Component identifier for the prime 1 component of private RSA CRT keys.
`static long`	`COMPONENT_PRIME_2` Component identifier for the prime 2 component of private RSA CRT keys.
`static long`	`COMPONENT_PRIVATE_EXPONENT` Component identifier for the private exponent component of RSA private keys.
`static long`	`COMPONENT_PUBLIC_EXPONENT` Component identifier for the public exponent component of RSA keys.
`static long`	`COMPONENT_VALUE` Component identifier for the value component of symmetric keys.
`static long`	`COMPONENT_VALUE_LENGTH` Component identifier for the value length of secret keys.
`static long`	`TYPE_PRIVATE_KEY` Key type constant for private (asymmetric) keys.
`static long`	`TYPE_PUBLIC_KEY` Key type constant for public keys.
`static long`	`TYPE_SECRET_KEY` Key type constant for secret (symmetric) keys.
`static long`	`USAGE_DECRYPTION` Key usage identifier for decryption.
`static long`	`USAGE_ENCRYPTION` Key usage identifier for encryption.
`static long`	`USAGE_SIGNATURE_CREATION` Key usage identifier for signature creation.
`static long`	`USAGE_SIGNATURE_VERIFICATION` Key usage identifier for signature verification.
`static long`	`USAGE_UNWRAP` Key usage identifier for key-unwrapping.
`static long`	`USAGE_WRAP` Key usage identifier for key-wrapping.

Method Summary
`boolean`	`canBeUsedFor(long usage)` This method determines if this key can be used for a certain purpose.
`java.lang.String`	`getAlgorithm()` Get the algorithm name of this key.
`java.lang.Object`	`getComponent(long componentType)` Get a specific component of this key; e.g. the modulus of an RSA key, or the value of a secret key.
`long`	`getType()` Get the key type.
`void`	`releaseSession()` If this key is not a key which is permanently stored on the token (e.g. a temporary secret key), this method releases the session of the key.
`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.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_PRIVATE_KEY

public static final long TYPE_PRIVATE_KEY

Key type constant for private (asymmetric) keys.

See Also:: Constant Field Values

TYPE_PUBLIC_KEY

public static final long TYPE_PUBLIC_KEY

Key type constant for public keys.

See Also:: Constant Field Values

TYPE_SECRET_KEY

public static final long TYPE_SECRET_KEY

Key type constant for secret (symmetric) keys.

See Also:: Constant Field Values

ALGORITHM_RSA

public static final java.lang.String ALGORITHM_RSA

Algorithm identifier for RSA keys.

See Also:: Constant Field Values

ALGORITHM_DSA

public static final java.lang.String ALGORITHM_DSA

Algorithm identifier for DSA keys.

See Also:: Constant Field Values

ALGORITHM_DH

public static final java.lang.String ALGORITHM_DH

Algorithm identifier for Diffie-Hellman keys.

See Also:: Constant Field Values

ALGORITHM_EC

public static final java.lang.String ALGORITHM_EC

Algorithm identifier for elliptic curve keys.

See Also:: Constant Field Values

ALGORITHM_ECDSA

public static final java.lang.String ALGORITHM_ECDSA

Algorithm identifier for elliptic curve DSA keys.

See Also:: Constant Field Values

ALGORITHM_AES

public static final java.lang.String ALGORITHM_AES

Algorithm identifier for AES keys.

See Also:: Constant Field Values

ALGORITHM_DES

public static final java.lang.String ALGORITHM_DES

Algorithm identifier for DES keys.

See Also:: Constant Field Values

ALGORITHM_DESEDE

public static final java.lang.String ALGORITHM_DESEDE

Algorithm identifier for Triple DES keys.

See Also:: Constant Field Values

ALGORITHM_IDEA

public static final java.lang.String ALGORITHM_IDEA

Algorithm identifier for IDEA keys.

See Also:: Constant Field Values

ALGORITHM_RC2

public static final java.lang.String ALGORITHM_RC2

Algorithm identifier for RC2 keys.

See Also:: Constant Field Values

ALGORITHM_RC4

public static final java.lang.String ALGORITHM_RC4

Algorithm identifier for RC4 keys.

See Also:: Constant Field Values

ALGORITHM_GENERIC

public static final java.lang.String ALGORITHM_GENERIC

Algorithm identifier for generic symmetric keys.

See Also:: Constant Field Values

COMPONENT_VALUE

public static final long COMPONENT_VALUE

Component identifier for the value component of symmetric keys. All symmetric keys have a value component which contains the key material. However, this component may be access-protected (i.e. unreadable).

See Also:: Constant Field Values

COMPONENT_MODULUS

public static final long COMPONENT_MODULUS

Component identifier for the modulus component of RSA keys. All RSA private and public keys have this component.

See Also:: Constant Field Values

COMPONENT_PUBLIC_EXPONENT

public static final long COMPONENT_PUBLIC_EXPONENT

Component identifier for the public exponent component of RSA keys. All RSA private and public keys have this component.

See Also:: Constant Field Values

COMPONENT_PRIVATE_EXPONENT

public static final long COMPONENT_PRIVATE_EXPONENT

Component identifier for the private exponent component of RSA private keys. Only RSA private keys have this component. However, this component may be access-protected (i.e. unreadable).

See Also:: Constant Field Values

COMPONENT_PRIME_1

public static final long COMPONENT_PRIME_1

Component identifier for the prime 1 component of private RSA CRT keys. Only private RSA CRT keys may have this component. However, this component may be access-protected (i.e. unreadable) if set at all.

See Also:: Constant Field Values

COMPONENT_PRIME_2

public static final long COMPONENT_PRIME_2

Component identifier for the prime 2 component of private RSA CRT keys. Only private RSA CRT keys may have this component. However, this component may be access-protected (i.e. unreadable) if set at all.

See Also:: Constant Field Values

COMPONENT_EXPONENT_1

public static final long COMPONENT_EXPONENT_1

Component identifier for the prime exponent 1 component of private RSA CRT keys. Only private RSA CRT keys may have this component. However, this component may be access-protected (i.e. unreadable) if set at all.

See Also:: Constant Field Values

COMPONENT_EXPONENT_2

public static final long COMPONENT_EXPONENT_2

Component identifier for the prime exponent 2 component of private RSA CRT keys. Only private RSA CRT keys may have this component. However, this component may be access-protected (i.e. unreadable) if set at all.

See Also:: Constant Field Values

COMPONENT_COEFFICIENT

public static final long COMPONENT_COEFFICIENT

Component identifier for the CRT coefficient component of private RSA CRT keys. Only private RSA CRT keys may have this component. However, this component may be access-protected (i.e. unreadable) if set at all.

See Also:: Constant Field Values

COMPONENT_VALUE_LENGTH

public static final long COMPONENT_VALUE_LENGTH

Component identifier for the value length of secret keys. This specifies the length of the key value in number of bytes.

See Also:: Constant Field Values

USAGE_SIGNATURE_CREATION

public static final long USAGE_SIGNATURE_CREATION

Key usage identifier for signature creation.

See Also:: Constant Field Values

USAGE_SIGNATURE_VERIFICATION

public static final long USAGE_SIGNATURE_VERIFICATION

Key usage identifier for signature verification.

See Also:: Constant Field Values

USAGE_ENCRYPTION

public static final long USAGE_ENCRYPTION

Key usage identifier for encryption.

See Also:: Constant Field Values

USAGE_DECRYPTION

public static final long USAGE_DECRYPTION

Key usage identifier for decryption.

See Also:: Constant Field Values

USAGE_WRAP

public static final long USAGE_WRAP

Key usage identifier for key-wrapping.

See Also:: Constant Field Values

USAGE_UNWRAP

public static final long USAGE_UNWRAP

Key usage identifier for key-unwrapping.

See Also:: Constant Field Values

Method Detail

canBeUsedFor

public boolean canBeUsedFor(long usage)
                     throws PKCS11RuntimeException

This method determines if this key can be used for a certain purpose. Valid usage values are all constants starting with USAGE_; e.g. USAGE_SIGNATURE_CREATION.

Parameters:: usage - The usage identifier; e.g. USAGE_SIGNATURE_CREATION.
Returns:: true if this key can be used for this purpose.
Throws:: PKCS11RuntimeException - If getting the key required key attribute fails.

getAlgorithm

public java.lang.String getAlgorithm()
                              throws PKCS11RuntimeException

Get the algorithm name of this key.

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

Returns:: The name of the key algorithm or null if the key has an unknown algorithm.
Throws:: PKCS11RuntimeException - If getting the key type attribute fails.

getType

public long getType()

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

Returns:: The key type.

getComponent

public java.lang.Object getComponent(long componentType)
                              throws PKCS11Exception,
                                     PKCS11RuntimeException

Get 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 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 object and has the value null, and if the attribute is present but is sensitive (i.e. protected);e.g the private exponent of RSA private keys.

If the key does not possess the requested component, this method will throw the checked exception PKCS11Exception. For example, if the application tries to get the COMPONENT_MODULUS from a DES key.

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 or sensitive.
Throws:: PKCS11Exception - If the key does not possess the requested component.; PKCS11RuntimeException - If getting the component failed for some other reason.

setComponent

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

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.

releaseSession

public void releaseSession()
                    throws PKCS11RuntimeException

If this key is not a key which is permanently stored on the token (e.g. a temporary secret key), this method releases the session of the key. This will cause the key to be deleted. After this call, this key object cannot be used any longer. For permanent keys like private keys which are stored on the token, this method does nothing.

Throws:: PKCS11RuntimeException - If releasing the session fails.