com.safenetinc.luna.provider

Class LunaKeyStore

java.lang.Object

java.security.KeyStoreSpi

com.safenetinc.luna.provider.LunaKeyStore

public class LunaKeyStore
extends java.security.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.

Object Caching can be enabled for the LunaKeyStore by adding a line with "caching:true".
If Caching is enabled the number of loading threads can be specified by adding a line with "loadingthreads:<number of threads>".
If caching is enabled, adding a line with "cachingstrict:true" will prevent the LunaKeystore from accessing the HSM to search for the object if the object isn't found in the cache.
If caching is enabled, adding a line with "clearcache:false" will prevent the object cache from being cleared when the LunaKeyStore is loaded.
If caching is enabled, adding a line with "loadcache:false" will prevent the object cache from being loaded when the LunaKeyStore is loaded.

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.

If strict adherence to the Java KeyStore API spec is desired then add the line with "defertokenization:true".
If defertokenization is set to true, then all KeyStore-affecting operations will not take effect until a KeyStore.store() call is made at which time all changes are persisted. Prior to the store() call, all changes are in a staging state which is lost if the application terminates or if the KeyStore object is lost before the store() call.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CACHING_STRICT_TAG
static java.lang.String	CACHING_TAG
static java.lang.String	CKU_CRYPTO_OFFICER
static java.lang.String	CKU_CRYPTO_USER
static java.lang.String	CKU_LIMITED_CRYPTO_OFFICER
static java.lang.String	CLEAR_CACHE_TAG
static java.lang.String	DEFERTOKENIZATION_TAG
static java.lang.String	LABEL_TAG
static java.lang.String	LOAD_CACHE_TAG
static java.lang.String	LOADING_THREADS_TAG
static java.lang.String	SLOT_TAG
static java.lang.String	USER_TYPE_TAG

Constructor Summary

Constructors

Constructor and Description
LunaKeyStore() Creates a new LunaKeyStore

Method Summary

Methods

Modifier and Type	Method and Description
void	deleteEntryFromFile(java.lang.String alias)
java.util.Enumeration<java.lang.String>	engineAliases()
boolean	engineContainsAlias(java.lang.String alias)
void	engineDeleteEntry(java.lang.String alias)
boolean	engineEntryInstanceOf(java.lang.String alias, java.lang.Class<? extends java.security.KeyStore.Entry> entryClass) Determines if the keystore Entry for the specified alias is an instance or subclass of the specified entryClass.
java.security.cert.Certificate	engineGetCertificate(java.lang.String alias)
java.lang.String	engineGetCertificateAlias(java.security.cert.Certificate certificate)
java.security.cert.Certificate[]	engineGetCertificateChain(java.lang.String alias)
java.util.Date	engineGetCreationDate(java.lang.String alias)
java.security.Key	engineGetKey(java.lang.String alias, char[] password)
boolean	engineIsCertificateEntry(java.lang.String alias)
boolean	engineIsKeyEntry(java.lang.String alias)
void	engineLoad(java.io.InputStream inputStream, char[] password) The Luna KeyStore reads data from one PKCS11 slot.
boolean	engineProbe(java.io.InputStream stream) This is needed for JDK9+ as using keytool generates an exception without it when one is pointing to LunaProvider.
void	engineSetCertificateEntry(java.lang.String alias, java.security.cert.Certificate certificate)
void	engineSetKeyEntry(java.lang.String alias, byte[] key, java.security.cert.Certificate[] certificate)
void	engineSetKeyEntry(java.lang.String alias, java.security.Key key, char[] password, java.security.cert.Certificate[] certificateChain)
int	engineSize()
void	engineStore(java.io.OutputStream outputStream, char[] password)
static boolean	getDeferTokenizationToStoreCall()
static void	init()
protected static boolean	isCertChainEntry(java.lang.String alias)
static void	setDeferTokenizationToStoreCall(boolean enabled)

Methods inherited from class java.security.KeyStoreSpi

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 java.lang.String LABEL_TAG

See Also:

Constant Field Values

SLOT_TAG

public static final java.lang.String SLOT_TAG

See Also:

Constant Field Values

USER_TYPE_TAG

public static final java.lang.String USER_TYPE_TAG

See Also:

Constant Field Values

CKU_CRYPTO_OFFICER

public static final java.lang.String CKU_CRYPTO_OFFICER

See Also:

Constant Field Values

CKU_CRYPTO_USER

public static final java.lang.String CKU_CRYPTO_USER

See Also:

Constant Field Values

CKU_LIMITED_CRYPTO_OFFICER

public static final java.lang.String CKU_LIMITED_CRYPTO_OFFICER

See Also:

Constant Field Values

CACHING_TAG

public static final java.lang.String CACHING_TAG

See Also:

Constant Field Values

CACHING_STRICT_TAG

public static final java.lang.String CACHING_STRICT_TAG

See Also:

Constant Field Values

LOADING_THREADS_TAG

public static final java.lang.String LOADING_THREADS_TAG

See Also:

Constant Field Values

CLEAR_CACHE_TAG

public static final java.lang.String CLEAR_CACHE_TAG

See Also:

Constant Field Values

LOAD_CACHE_TAG

public static final java.lang.String LOAD_CACHE_TAG

See Also:

Constant Field Values

DEFERTOKENIZATION_TAG

public static final java.lang.String DEFERTOKENIZATION_TAG

See Also:

Constant Field Values

Constructor Detail

LunaKeyStore

public LunaKeyStore()

Creates a new LunaKeyStore

Method Detail

init

public static void init()

setDeferTokenizationToStoreCall

public static void setDeferTokenizationToStoreCall(boolean enabled)

getDeferTokenizationToStoreCall

public static boolean getDeferTokenizationToStoreCall()

isCertChainEntry

protected static boolean isCertChainEntry(java.lang.String alias)

engineAliases

public java.util.Enumeration<java.lang.String> engineAliases()

Specified by:

engineAliases in class java.security.KeyStoreSpi

engineContainsAlias

public boolean engineContainsAlias(java.lang.String alias)

Specified by:

engineContainsAlias in class java.security.KeyStoreSpi

engineDeleteEntry

public void engineDeleteEntry(java.lang.String alias)
                       throws java.security.KeyStoreException

Specified by:

engineDeleteEntry in class java.security.KeyStoreSpi

Throws:

java.security.KeyStoreException

deleteEntryFromFile

public void deleteEntryFromFile(java.lang.String alias)

engineGetCertificate

public java.security.cert.Certificate engineGetCertificate(java.lang.String alias)

Specified by:

engineGetCertificate in class java.security.KeyStoreSpi

engineGetCertificateAlias

public java.lang.String engineGetCertificateAlias(java.security.cert.Certificate certificate)

Specified by:

engineGetCertificateAlias in class java.security.KeyStoreSpi

engineGetCertificateChain

public java.security.cert.Certificate[] engineGetCertificateChain(java.lang.String alias)

Specified by:

engineGetCertificateChain in class java.security.KeyStoreSpi

engineGetCreationDate

public java.util.Date engineGetCreationDate(java.lang.String alias)

Specified by:

engineGetCreationDate in class java.security.KeyStoreSpi

engineGetKey

public java.security.Key engineGetKey(java.lang.String alias,
                             char[] password)
                               throws java.security.NoSuchAlgorithmException,
                                      java.security.UnrecoverableKeyException

Specified by:

engineGetKey in class java.security.KeyStoreSpi

Parameters:

alias - key label

password - per-key password (unused by Luna)

Throws:

java.security.NoSuchAlgorithmException - exception

java.security.UnrecoverableKeyException - exception

engineIsCertificateEntry

public boolean engineIsCertificateEntry(java.lang.String alias)

Specified by:

engineIsCertificateEntry in class java.security.KeyStoreSpi

engineIsKeyEntry

public boolean engineIsKeyEntry(java.lang.String alias)

Specified by:

engineIsKeyEntry in class java.security.KeyStoreSpi

engineSetCertificateEntry

public void engineSetCertificateEntry(java.lang.String alias,
                             java.security.cert.Certificate certificate)
                               throws java.security.KeyStoreException

Specified by:

engineSetCertificateEntry in class java.security.KeyStoreSpi

Throws:

java.security.KeyStoreException

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String alias,
                     byte[] key,
                     java.security.cert.Certificate[] certificate)
                       throws java.security.KeyStoreException

Specified by:

engineSetKeyEntry in class java.security.KeyStoreSpi

Throws:

java.security.KeyStoreException

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String alias,
                     java.security.Key key,
                     char[] password,
                     java.security.cert.Certificate[] certificateChain)
                       throws java.security.KeyStoreException

Specified by:

engineSetKeyEntry in class java.security.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 and must not be null or empty).

Throws:

java.security.KeyStoreException - exception

engineSize

public int engineSize()

Specified by:

engineSize in class java.security.KeyStoreSpi

engineLoad

public void engineLoad(java.io.InputStream inputStream,
              char[] password)
                throws java.io.IOException,
                       java.security.NoSuchAlgorithmException,
                       java.security.cert.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.

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

Object Caching for the LunaKeyStore can be enabled and configured by adding the following lines:

• caching:true -- enables caching for the LunaKeyStore which can help with performance.
• loadingthreads:<number of threads> -- number of threads used to load keys and certificates. The default is 1.
• cachingstrict:true -- when set if the object isn't found in the object cache, then the LunaKeyStore will consider there to be no object with the given alias and will return null or false and will not access the HSM to search for the object. This option can be used to optimize the performance in certain scenarios when there are many keys in the partition. This setting is disabled by default.
• clearcache:false -- prevents the object cache from being cleared when the LunaKeyStore is loaded. The default is true.
• loadcache:false -- prevents the object cache from being loaded when the LunaKeyStore is loaded. The default is true.

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 java.security.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:

java.io.IOException

java.security.NoSuchAlgorithmException

java.security.cert.CertificateException

engineStore

public void engineStore(java.io.OutputStream outputStream,
               char[] password)
                 throws java.io.IOException,
                        java.security.NoSuchAlgorithmException,
                        java.security.cert.CertificateException

Specified by:

engineStore in class java.security.KeyStoreSpi

Throws:

java.io.IOException

java.security.NoSuchAlgorithmException

java.security.cert.CertificateException

engineEntryInstanceOf

public boolean engineEntryInstanceOf(java.lang.String alias,
                            java.lang.Class<? extends java.security.KeyStore.Entry> entryClass)

Determines if the keystore Entry for the specified alias is an instance or subclass of the specified entryClass.

Overrides:

engineEntryInstanceOf in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

entryClass - the entry class

Returns:

true if the keystore Entry for the specified alias is an instance or subclass of the specified entryClass, false otherwise

engineProbe

public boolean engineProbe(java.io.InputStream stream)
                    throws java.io.IOException

This is needed for JDK9+ as using keytool generates an exception without it when one is pointing to LunaProvider. The exception is innocuous but annoying and misleading.

Parameters:

stream - Input stream

Returns:

is KeyStore supported by this provider

Throws:

java.io.IOException - exception