|
Home > |
|---|
Luna JSP consists of a single JCA/JCE service provider, that allows a Java-based application to use SafeNet Luna 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.
You must acquire a Java JDK or JRE separately and install it before installing the Luna JSP. See the QuickStart that came with your software package.
In order to use the LunaProvider you must place the jar file in your classpath. We recommend placing it in your <jre>/lib/ext folder. In addition the JNI component, which may be a .dll or .so file depending on your system architecture, should be placed in your library path.
In general, you should use the standard JCA/JCE classes and methods to work with Luna HSMs. The following sections provide examples of when you may wish to use the special Luna methods.
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 Luna 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.
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.
The Luna JSP comes with several sample applications that show you how to use the Luna provider. The samples include detailed comments.
cd <Luna SA install>/jsp/samples
javac com\safenetinc\luna\sample\*.java
java com.safenetinc.luna.sample.KeyStoreLunaDemo (or any other sample class in that package)
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 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 Luna 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 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 behaviour.
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.
The Luna JSP may be used in combination with Java’s keytool utility to store and use keys on a Luna HSM, with the following limitations:
•You cannot use the importkeystore command to migrate keys from a Luna KeyStore to another KeyStore.
•Private keys cannot be extracted from the KeyStore unless you have the Key Export model of the HSM.
•By default secret keys created with the LunaProvider are non-extractable.
The example below uses a KeyStore file containing only the line “slot:1”. This tells the Luna KeyStore to use the token in slot 1.
For information on creating keys through Key Generator or Key Factory classes please see the LunaProvider Javadoc or the JCA/JCE API documentation.
Keys (with self signed certificates) can be generated using the keytool by specifying a valid Luna KeyStore file and specifying the KeyStore type as “Luna”. The password presented to authenticate to the KeyStore is the challenge password of the partition.
keytool –genkeypair –alias myKey –keyalg RSA –sigalg SHA256withRSA –keystore keystore.luna –storetype Luna
Enter keystore password:
What is your first and last name?
[Unknown]: test
What is the name of your organizational unit?
[Unknown]: codesigning
What is the name of your organization?
[Unknown]: SafeNet Inc
What is the name of your City or Locality?
[Unknown]: Ottawa
What is the name of your State or Province?
[Unknown]: ON
What is the two-letter country code for this unit?
[Unknown]: CA
Is CN=test, OU=codesigning, O=SafeNet Inc, L=Ottawa, ST=ON, C=CA correct?
[no]: yes
Enter key password for <myKey>
(RETURN if same as keystore password):
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.
Keys created using the SafeNet PKCS#11 API can be used with the Luna JSP; the inverse is also true.
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.
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.
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.