com.safenetinc.luna.provider

Class LunaKeyStore

java.lang.Object

java.security.KeyStoreSpi

com.safenetinc.luna.provider.LunaKeyStore

public class LunaKeyStore
extends KeyStoreSpi

This is the preferred means of managing Luna HSM access via the LunaProvider. This is the KeyStore engine class for storing objects on Luna hardware. The data in a Luna KeyStore corresponds to the objects in a hardware token. Like a JKS KeyStore, a Luna KeyStore must be loaded before being used. Unlike a JKS KeyStore, setting a key/certificate entry causes the key/certificate to be immediately written to the HSM as a token (permanent) object with the specified alias; the Luna provider does not wait until store() is called.

When no InputStream is specified, the KeyStore acts essentially as a front- end to the default HSM slot.

KeyStore ks = KeyStore.getInstance("Luna"); ks.load(null, "mypasswd".toCharArray());

The code above is the bare minimum necessary to get a Luna KeyStore up and running. This KeyStore is backed by the HSM partition that is at the currently specified default slot in LunaSlotManager. If no password is supplied in load, the user must log in via LunaSlotManager before using the keystore.

When the InputStream is backed by a file, the file should specify the slot to use in one of two formats. Using the string "tokenlabel:label" will attempt to open the KeyStore against the token with the provided label. Using "slot:<slotNum>" will attempt to open the KeyStore against the token at the provided slot. It is recommended that the token label be used, as the slot number of a given token may change but the label will not. As well, the user type can be specified by adding a line with "usertype:<user type>" with possible values of CKU_CRYPTO_USER or CKU_CRYPTO_OFFICER.

Using a file to back the InputStream in the load() method is optional. If there is no existing KeyStore file, a new KeyStore can be loaded by creating an InputStream backed by a String in one of the two formats above.

ByteArrayInputStream slot = new ByteArrayInputStream("slot:2".getBytes()); KeyStore ks = KeyStore.getInstance("Luna"); ks.load(slot, "mypasswd".toCharArray());

The code above will attempt to open a KeyStore on slot 2 with the partition password "mypasswd". Multiple KeyStores can be opened on the same slot, but they are not guaranteed to be thread-safe. External synchronization is recommended.

If an InputStream is provided that contains anything other than a string in one of the two formats above, the KeyStore will attempt to use the default slot.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CKU_CRYPTO_OFFICER
static String	CKU_CRYPTO_USER
static String	LABEL_TAG
static String	SLOT_TAG
static String	USER_TYPE_TAG

Constructor Summary

Constructors

Constructor and Description
LunaKeyStore() Creates a new LunaKeyStore

Method Summary

Modifier and Type	Method and Description
Enumeration<String>	engineAliases()
boolean	engineContainsAlias(String alias)
void	engineDeleteEntry(String alias)
Certificate	engineGetCertificate(String alias)
String	engineGetCertificateAlias(Certificate certificate)
Certificate[]	engineGetCertificateChain(String alias)
Date	engineGetCreationDate(String alias)
Key	engineGetKey(String alias, char[] password)
boolean	engineIsCertificateEntry(String alias)
boolean	engineIsKeyEntry(String alias)
void	engineLoad(InputStream inputStream, char[] password) The Luna KeyStore reads data from one PKCS11 slot.
void	engineSetCertificateEntry(String alias, Certificate certificate)
void	engineSetKeyEntry(String alias, byte[] key, Certificate[] certificate)
void	engineSetKeyEntry(String alias, Key key, char[] password, Certificate[] certificateChain)
int	engineSize()
void	engineStore(OutputStream outputStream, char[] password)

Methods inherited from class java.security.KeyStoreSpi

engineEntryInstanceOf, engineGetEntry, engineLoad, engineSetEntry, engineStore

Methods inherited from class java.lang.Object

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

Field Detail

LABEL_TAG

public static final String LABEL_TAG

See Also:

Constant Field Values

SLOT_TAG

public static final String SLOT_TAG

See Also:

Constant Field Values

USER_TYPE_TAG

public static final String USER_TYPE_TAG

See Also:

Constant Field Values

CKU_CRYPTO_OFFICER

public static final String CKU_CRYPTO_OFFICER

See Also:

Constant Field Values

CKU_CRYPTO_USER

public static final String CKU_CRYPTO_USER

See Also:

Constant Field Values

Constructor Detail

LunaKeyStore

public LunaKeyStore()

Creates a new LunaKeyStore

Method Detail

engineAliases

public Enumeration<String> engineAliases()

Specified by:

engineAliases in class KeyStoreSpi

engineContainsAlias

public boolean engineContainsAlias(String alias)

Specified by:

engineContainsAlias in class KeyStoreSpi

engineDeleteEntry

public void engineDeleteEntry(String alias)
                       throws KeyStoreException

Specified by:

engineDeleteEntry in class KeyStoreSpi

Throws:

KeyStoreException

engineGetCertificate

public Certificate engineGetCertificate(String alias)

Specified by:

engineGetCertificate in class KeyStoreSpi

engineGetCertificateAlias

public String engineGetCertificateAlias(Certificate certificate)

Specified by:

engineGetCertificateAlias in class KeyStoreSpi

engineGetCertificateChain

public Certificate[] engineGetCertificateChain(String alias)

Specified by:

engineGetCertificateChain in class KeyStoreSpi

engineGetCreationDate

public Date engineGetCreationDate(String alias)

Specified by:

engineGetCreationDate in class KeyStoreSpi

engineGetKey

public Key engineGetKey(String alias,
                        char[] password)
                 throws NoSuchAlgorithmException,
                        UnrecoverableKeyException

Specified by:

engineGetKey in class KeyStoreSpi

Parameters:

alias - key label

password - per-key password (unused by Luna)

Throws:

NoSuchAlgorithmException - exception

UnrecoverableKeyException - exception

engineIsCertificateEntry

public boolean engineIsCertificateEntry(String alias)

Specified by:

engineIsCertificateEntry in class KeyStoreSpi

engineIsKeyEntry

public boolean engineIsKeyEntry(String alias)

Specified by:

engineIsKeyEntry in class KeyStoreSpi

engineSetCertificateEntry

public void engineSetCertificateEntry(String alias,
                                      Certificate certificate)
                               throws KeyStoreException

Specified by:

engineSetCertificateEntry in class KeyStoreSpi

Throws:

KeyStoreException

engineSetKeyEntry

public void engineSetKeyEntry(String alias,
                              byte[] key,
                              Certificate[] certificate)
                       throws KeyStoreException

Specified by:

engineSetKeyEntry in class KeyStoreSpi

Throws:

KeyStoreException

engineSetKeyEntry

public void engineSetKeyEntry(String alias,
                              Key key,
                              char[] password,
                              Certificate[] certificateChain)
                       throws KeyStoreException

Specified by:

engineSetKeyEntry in class KeyStoreSpi

Parameters:

alias - key label

key - key object to be associated with the alias

password - per-key password (unused by Luna)

certificateChain - the certificate chain for the corresponding public key (only required if the given key is of type java.security.PrivateKey).

Throws:

KeyStoreException - exception

engineSize

public int engineSize()

Specified by:

engineSize in class KeyStoreSpi

engineLoad

public void engineLoad(InputStream inputStream,
                       char[] password)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException

The Luna KeyStore reads data from one PKCS11 slot. The slot number can be specified by having the InputStream contain a String that matches one of two forms:

• tokenlabel:<label> -- the labels of all available slots are matched against <label>. If a match is found, the KeyStore is set to read from the token at that slot.
• slot:<slotNumber> -- the KeyStore is set to read from the token at the given slot number.

As well, the user type can be specified by adding the following on a separate line:

• usertype:<user type> -- the keystore will login to the HSM using the specifed <user type>. The possible values are CKU_CRYPTO_USER or CKU_CRYPTO_OFFICER

If the InputStream is null or contains data of any format other than the above, the KeyStore is set to read from the token at the current default slot number.

Specified by:

engineLoad in class KeyStoreSpi

Parameters:

inputStream - Determines the slot the keystore is loaded against as described above

password - Password for the slot. If no password is given, keystore operations will fail unless the user logs in to the slot directly using LunaSlotManager, or is already logged in

Throws:

IOException

NoSuchAlgorithmException

CertificateException

engineStore

public void engineStore(OutputStream outputStream,
                        char[] password)
                 throws IOException,
                        NoSuchAlgorithmException,
                        CertificateException

Specified by:

engineStore in class KeyStoreSpi

Throws:

IOException

NoSuchAlgorithmException

CertificateException