LunaKeyStore Reference

This page reproduces information found in the Luna JSP javadocs.

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.