Luna JSP Configuration

Luna JSP consists of a single JCA/JCE service provider, that allows a Java-based application to use Luna Cloud HSM products for secure cryptographic operations. Please refer to the Javadocs accompanying the toolkit, for the most current information regarding the Luna JSP packages and LunaProvider functionality.

To install JSP, refer to Luna JSP Overview and Installation.

Luna Java Security Provider

In general, you should use the standard JCA/JCE classes and methods to work with Luna Cloud HSM. The following sections provide examples of when you may wish to use the special Luna methods.

Class Hierarchy

All public classes in the Luna Java crypto provider are included in the com.safenetinc.luna package or subpackages of that package. Thus the full class names are (for example):

>com.safenetinc.luna.LunaSlotManager

>com.safenetinc.luna.provider.key.LunaKey

If your application is compliant with the JCA/JCE spec, you will generally not need to directly reference any SafeNet implementation classes. Use the interfaces defined in the java.security packages instead. The exception is if you need to perform an HSM-specific operation, such as modifying PKCS#11 attributes.

Throughout the rest of this document, the short form of the class names is used for convenience and readability. The full class names (of SafeNet or other classes) are used only where necessary to resolve ambiguity.

Special Classes/Methods

The JCA/JCE interfaces were not designed with hardware security modules (HSMs) in mind and do not include methods for managing aspects of a hardware module. Luna JSP provides some additional functions in addition to the standard JCA/JCE API.

The LunaSlotManager class provides custom methods that allow some HSM-specific information to be retrieved. It also provides a way to log in to the HSM if your application cannot make use of the standard KeyStore interface. For details please check the Javadoc which comes with the product.

It is not always necessary to use the LunaSlotManager class. With proper use of the JCE API provided in Luna JSP, your code can be completely hardware-agnostic.

The LunaKey class implements the Key interface and provides all of the methods of that class along with custom methods for manipulating key objects on Luna hardware.

NOTE   Sensitive attributes cannot be retrieved from keys stored on Luna hardware. Thus certain JCE-specified methods (such as PrivateKeyRSA.getPrivateExponent()) will throw an exception.

The LunaCertificateX509 class implements the X509Certificate methods along with custom methods for manipulating certificate objects on Luna hardware.

Signature Verification in Software

Using HSM Client 10.7.0 or newer, you can enable the following settings in the java.Security file to allow some algorithms to perform signature verification in software:

>com.safenetinc.luna.provider.verifyInSoftware=<setting>

When <setting> is true, signature verification is performed in software. When <setting> is false (default), it is performed using the HSM.

>com.safenetinc.luna.provider.verifyInSoftwareProvider=<provider>

In this setting, <provider> specifies the provider to be used for the signature verification (default: SunRsaSign).

NOTE   This default setting requires minimum Java JDK 1.8.0-251.

Examples

The Luna JSP comes with several sample applications that show you how to use the Luna provider. The samples include detailed comments.

To compile on Windows without an IDE (Administrator privileges may be required):

cd <Luna Cloud HSM install>/jsp/samples
javac com\safenetinc\luna\sample\*.java

To run:

java com.safenetinc.luna.sample.KeyStoreLunaDemo (or any other sample class in that package)

NOTE   The Luna Keystore is not a physical file like a regular JKS. It is a virtual interface to the HSM and contains only handles for the private key objects.

Authenticating to the HSM

In order to make use of an HSM, it is necessary to activate the device through a login. Depending on the security level of the device, the login will require a plain-text password and/or a PED key.

The preferred method of logging in to the module is through the Java KeyStore interface. The store type is “Luna” and the password for the key store is the challenge for the partition specified.

KeyStore files for the Luna KeyStore must be created manually. The content of the KeyStore file differs if you wish to reference the partition by the slot number or label (preferred). Details of authenticating to the HSM via the KeyStore interface are explained in the Javadoc for LunaKeyStore and in the KeyStoreLunaDemo sample application.

Keys in a Luna KeyStore cannot have individual passwords. Only the KeyStore password is used. If your HSM requires PED keys to be presented for authentication and the partition is not already activated, loading the KeyStore will cause the PED to prompt you to present this key.

Other than the KeyStore interface your application may also make use of the LunaSlotManager class or by using a login state created outside of the application through a utility called ‘salogin’. Use of salogin is strongly discouraged unless you have a very specific need.

LunaKeyStoreMP is Deprecated

LunaKeyStoreMP is deprecated for Luna JSP, and may be discontinued in a future release. LunaKeyStoreMP was used in previous releases to allow logical partitioning of the key space on HSMs that have only one partition. This allowed you to create a separate MP key store for each individual client that accessed the partition. Recent SafeNet releases, however, support multiple partitions, and dedicating a partition per client is a superior solution for management and security reasons.

NOTE   LunaKeyStoreMP is retained for backwards compatibility reasons only. Do not use LunaKeyStoreMP when creating new applications.

Logging Out

Logging out of the HSM is performed implicitly when the application is terminated normally. Logging out of the HSM while the application is running can be done with the LunaSlotManager class. Please note that any ephemeral (non-persistent) key material present on the HSM will be destroyed when the session is logged out. Because the link to the HSM will be severed, cryptographic objects that were created by the LunaProvider will no longer be usable. Attempting to use these objects after logging out will result in undefined behavior.

All key material which was persisted on the HSM (either through the KeyStore interface or using the proprietary Make Persistent method) will remain on the HSM after a logout and will be accessible again when the application logs back in to the HSM.

Keytool

The Luna JSP may be used in combination with Java’s keytool utility to store and use keys on a Luna Cloud HSM, see Using Java Keytool with Luna Cloud HSM.

Cleaning Up

Keys that are made persistent will continue to exist on the HSM until they are explicitly destroyed, or until the HSM is reinitialized. Persistent keys that are no longer needed can be explicitly destroyed to free resources on the HSM.

Keys may be removed using the Keytool, or programmatically through the KeyStore interface or other methods available through the API.

LunaSlotManager contains methods that report the number of objects that exist on the HSM. See the Javadoc for LunaSlotManager for more information.

PKCS#11/JCA Interaction

Keys created using the Luna PKCS#11 API can be used with the Luna JSP; the inverse is also true.

Certificate Chains

The PKCS#11 standard does not provide a certificate chain representation. When a Java certificate chain is stored on a Luna token, the certificates of the chain appear as individual objects when viewed through the PKCS#11 API. In order for the LunaProvider to properly identify PKCS#11-created certificates as part of a chain attached to a private key, the certificates must follow the labeling scheme described below.

Java Aliases and PKCS#11 Labels

The PKCS#11 standard defines a large set of object attributes, including the object label. This label is analogous to the Object alias in a java KeyStore.

The Luna KeyStore key entry or a Luna KeyStore certificate entry will have a PKCS#11 object label exactly equal to the Java alias. Similarly, a key created through PKCS#11 will have a Java alias equal to the PKCS#11 label.

Because a java certificate chain cannot be represented as a single PKCS#11 object, the individual certificates in the chain will each appear as individual PKCS#11 objects. The labels of these PKCS#11 objects will be composed of the alias of the corresponding key entry, concatenated with "--certX", where 'X' is the index of the certificate in the java certificate chain.

For example, consider a token that has a number of objects created through the Java API. The objects consist of the following:

>A key entry with alias "signing key", consisting of a private key and a certificate chain of length 2

>A trusted certificate entry with alias "root cert"

>A secret key with alias "session key"

If all objects on the token were viewed through a PKCS#11 interface, 5 objects would be seen:

>A private key with label "signing key"

>A certificate with label "signing key--cert0"

>A certificate with label "signing key--cert1"

>A certificate with label "root cert"

> A secret key with label "session key"

NOTE   PKCS#11 labels (strings of ascii characters) and Java aliases (of the java.lang.String type) are usually fully compatible, but problems can arise if non-printable characters are used. To maintain compatibility between Java and PKCS#11, avoid embedding non-printable or non-ascii characters in aliases or object labels.

RSA Cipher

Previously, by default, the Luna JSP RSA cipher mode used raw RSA X.509 encryption, with no padding.

For improved security and compatibility, default padding for RSA cipher has been changed from NoPadding to PKCS1v1_5.