iaik.pkcs.pkcs11.me
Class KeyStore

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

public class KeyStore

extends java.lang.Object

An object of this class offers a key store view of a token similar to a java.security.KeyStore object.

Attention! The key store may contain more or less entries depending on the login state of the token. If the user is not logged in to the token, the key store may only show public objects like certificates but no private keys. Thus, it is recommended to login the user to the token using Token.loginUser(char[]) before searching for keys in the key store.

The key store reads the token contents upon first access to any of its methods, and each time update() is called. The key store does never automatically update the its entries otherwise. Hence, the application should call update() if the token contents may have changed; e.g. due to a key-pair generation.

Each entry in a key store has a unique alias name, which is a string. The aliases of all entries are accessible through the aliases() method.
In general there are two different types of entries: key entries and certificate entries. The application can determine the type of an entry with the isKeyEntry(String) and the isCertificateEntry(String) methods. With a key entry, there can be a certificate associated. This associated certificate does not count as a separate certificate entry then, but is referenced via the same alias as its key; i.e. the application calls getCertificate(String) providing the key alias to get the associated certificate. Typically, private keys may have certificates associated with them.

This class handles keys as Key objects and certificates in their DER encoded form.

A typical piece of code reading the contents of a key store may look like this:

  Token token = ... // get token from module
  KeyStore keyStore = token.getKeyStore();
  char[] pin = ... // get PIN for user login
  token.loginUser(pin);
  Enumeration aliases = keyStore.aliases();
  while (aliases.hasMoreElements()) {
    String alias = (String) aliases.nextElement();
    if (keyStore.isKeyEntry(alias)) {
      Key key = keyStore.getKey(alias);
      byte[] certificate = keyStore.getCertificate(alias);
      if (certificate != null) {
        // there is a certificate associated to this key
      } 
    }
    if (keyStore.isCertificateEntry(alias)) {
      byte[] certificate = keyStore.getCertificate(alias);
    }
  }
 

Please note that this class is not thread safe.

See Also:

Key

Method Summary

java.util.Enumeration	aliases() List the alias names of all entries of this key store.
void	delete(java.lang.String alias) Delete the key store entry with the given alias.
byte[]	getCertificate(java.lang.String alias) Get the DER encoded certificate of a certificate entry or of a associated certificate of a key.
Key	getKey(java.lang.String alias) Get the key object of a key entry.
boolean	isCertificateEntry(java.lang.String alias) This method checks if an alias name refers to a certificate entry.
boolean	isKeyEntry(java.lang.String alias) This method checks if an alias name refers to a key entry.
void	setCertificate(java.lang.String alias, byte[] certificate, byte[] subjectDN) Put a certificate in this key store.
Key	setKey(java.lang.String alias, KeyTemplate template) Set a key entry.
void	update() Update the entries of this key store from the underlying token; i.e. read all key and certificate entries again from the token.

Methods inherited from class java.lang.Object

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

Method Detail

aliases

public java.util.Enumeration aliases()
                              throws PKCS11RuntimeException

List the alias names of all entries of this key store. This takes all type of entries into account.

Returns:

An enumeration of the aliases of all entries. All elements of this enumeration are of type String.

Throws:

PKCS11RuntimeException - If reading the token contents fails.

See Also:

isKeyEntry(String), isCertificateEntry(String), getKey(String), getCertificate(String)

getKey

public Key getKey(java.lang.String alias)
           throws PKCS11RuntimeException

Get the key object of a key entry. This method will return a non-null value if the alias refers to a key entry.

Parameters:

alias - The alias of the key entry.

Returns:

The key object of the key entry or null if the alias does not refer to a key entry.

Throws:

PKCS11RuntimeException - If reading the token contents fails.

See Also:

aliases(), isKeyEntry(String)

getCertificate

public byte[] getCertificate(java.lang.String alias)
                      throws PKCS11RuntimeException

Get the DER encoded certificate of a certificate entry or of a associated certificate of a key. This method will return a non-null value if the alias refers to a certificate entry or to a certificate which is associated with a key.

Parameters:

alias - The alias of the certificate entry.

Returns:

The key object of the certificate entry or null if the alias does not refer to a certificate entry or to a certificate which is associated with a key.

Throws:

PKCS11RuntimeException - If reading the token contents fails.

See Also:

aliases(), isCertificateEntry(String), isKeyEntry(String)

isKeyEntry

public boolean isKeyEntry(java.lang.String alias)

This method checks if an alias name refers to a key entry. If this method returns true, the application can call getKey(String) to get the key object of this entry. Moreover, it can call getCertificate(String) to get an associated certificate of the key entry.

Parameters:

alias - The alias name.

Returns:

true if the alias name refers to a key entry.

See Also:

aliases(), getKey(String), getCertificate(String)

isCertificateEntry

public boolean isCertificateEntry(java.lang.String alias)

This method checks if an alias name refers to a certificate entry. If this method returns true, the application can call getCertificate(String) to get the DER encoded certificate of the certificate entry.
Note that this method returns false for aliases which refer to key entries with associated certificates.

Parameters:

alias - The alias name.

Returns:

true if the alias name refers to a certificate entry.

See Also:

aliases(), getCertificate(String)

setCertificate

public void setCertificate(java.lang.String alias,
                           byte[] certificate,
                           byte[] subjectDN)
                    throws PKCS11RuntimeException

Put a certificate in this key store.

If the alias refers to an already existing key entry (i.e. isKeyEntry(String) returns true), then the new object becomes a certificate which is associated with this key entry. The old associated certificate will be deleted.

If the alias does not refer to an existing entry, a new certificate entry will be created.

If the alias refers to an existing certificate entry (i.e. isCertificateEntry(String) returns true), the old entry will be deleted and a new certificate entry will be created.

If the application can parse the certificate, it is recommended that it passes the DER encoded subject DN of this certificate to this method. This is, because the underlying PKCS#11 module may require it for creating a certificate object on the token. This method does not have any means to parse the subject DN out of the given certificate.

Parameters:

alias - The alias name.

certificate - The DER encoded certificate.

subjectDN - The DER encoded subject DN of this certificate. May be null if unavailable; e.g. if the application cannot parse it out of the certificate.

Throws:

PKCS11RuntimeException

See Also:

aliases(), isKeyEntry(String), isCertificateEntry(String), getCertificate(String)

setKey

public Key setKey(java.lang.String alias,
                  KeyTemplate template)
           throws PKCS11Exception,
                  PKCS11RuntimeException

Set a key entry. This creates a new entry if the given alias does not exist, or replaces an exiting entry with the same alias.

The application must have set all key components in the template.

Parameters:

alias - The alias name for the key.

template - The template which contains the key components.

Returns:

The newly created key.

Throws:

PKCS11Exception - If the template is invalid.

PKCS11RuntimeException - If creating a new key fails or if deleting an old key fails.

delete

public void delete(java.lang.String alias)
            throws PKCS11RuntimeException

Delete the key store entry with the given alias. This method will delete key entries as well as certificate entries. If there is no entry with the given alias, this method does nothing.

Parameters:

alias - The alias name of the entry.

Throws:

PKCS11RuntimeException - If deleting an object fails.

update

public void update()

Update the entries of this key store from the underlying token; i.e. read all key and certificate entries again from the token.