Luna JSP Overview and Installation
The Luna JSP is part of an application program interface (API) that allows Java applications to make use of certain Luna products.
As with other APIs, some existing Java-based applications might have generic requirements and calls that can already work with Luna products. In other cases, it might be necessary for you or your vendor to create an application or to adapt one, using the JSP API.
You have the choice of:
>using a previously integrated third-party application, known to work with this Luna product
>performing your own integration with a Java-based application supplied by you or a third party, or
>developing your own application using our Java API.
Develop your own Java apps using our included Software Development Kit, which includes Luna Java API usage notes for developers, as well as development support by Thales. A standard Java development environment is required, in addition to the API provided by Thales.
Please refer to the current-version Luna USB HSM 7 Customer Release Notes (CRN) for the most up-to-date list of supported platforms and APIs.
NOTE Java Provider (JSP) - both GMC and GMAC are supported. GmacAesDemo.java provides a sample for using GMAC with Java.
Java Parameter Specification class LunaGmacParameterSpec.java defines default values recommended by the NIST specification.
This following sections describe the tasks required to set up the JSP API:
Installation
To use the Luna JavaSP service providers three main components are needed:
>The Java SDK
>The Java Cryptographic JCE Policy files (optional)
>The Luna JavaSP artifacts in the Luna HSM Client
Java SDK Installation
Acquire and install the JDK or JRE (available from the Java site, not included with the Luna software). Refer to the Customer Release Notes for supported Java versions.
Java Cryptographic JCE Policy Files Installation (optional)
If you intend to generate large key sizes, you might need to apply the unlimited strength ciphers policy. You will need two cryptographic JCE Policy files v 7/8/9/10/11 (available from the Oracle Java web site): local_policy.jar and US_export_policy.jar.
Copy these files to JAVA_HOME/jre/lib/security (or the equivalent directory that applies to your setup).
[root@my-client]# echo $JAVA_HOME /usr/java/default [root@my-client]# cp -p local_policy.jar /usr/java/default/jre/lib/security/ [root@my-sclient]# cp -p US_export_policy.jar /usr/java/default/jre/lib/security/
If you see errors like "Invalid Key size", that is usually an indication that the JCE is not properly installed.
Luna JavaSP included in the Luna HSM Client
Follow the installation
procedure for the Luna HSM Client as described in the Installation Guide.
| Operating System | JSP Install directory |
|---|---|
| Linux |
/usr/safenet/lunaclient/jsp/lib |
| Windows |
C:\Program Files\LunaClient\JSP\lib |
To configure Java 7/8 for Luna JSP
To ensure that Luna USB HSM 7 and Luna JSP can work with the JRE, copy the JSP files from the default installation location to the Java environment. The exact destination directory might differ depending on where you obtained your Java system, the version, and any choices that you made while installing and configuring it.
| Operating System | Destination directory example |
|---|---|
| Linux | /usr/jre/lib/ext |
| Windows |
<java_install_dir>\bin C:\Program Files\Java\jdk1.8.0_121\bin NOTE Java 7/8/9 for Windows has removed the <java_install_dir>\lib\ext directory from the Java library path. |
IBM Java 7/8 has a .jar authentication issue that requires a patch from IBM. See APAR IJ25459 for details.
To configure Java 9+ for Luna JSP
Add LunaProvider.jar to the Java classpath and specify the Luna Java library location (libLunaAPI.so in Unix based systems or LunaAPI.dll in Windows systems) in the Java library path.
For example:
> java -cp /<directory_location>/LunaProvider.jar -Djava.library.path=<Luna_Java_library_location> <class name>
TIP In Windows, you can also put LunaAPI.dll in an arbitrary folder and add that folder to the system path. Java will search the system path for LunaAPI.dll.
The exact directory might differ depending on where you obtained your Java system, the version, and any choices that you made while installing and configuring it.
JSP Registration
Before Java can use Luna JSP, you must register it with the Java Runtime Enviroment. You can choose either a static registration or a dynamic registration. A static registration defaults all Java applications to default to the Luna provider, while a dynamic registration allows you to set the provider for Java applications individually.
JSP Static Registration
NOTE This section applies to JSP, not to JCPROV.
You would choose static registration of providers if you want all applications to default to the Luna provider.
Once your client has externally logged in
Edit the java.security file located in the /jre/lib/security directory of your Java SDK/JRE installation to read as follows:
security.provider.1=sun.security.provider.Sun security.provider.2=com.sun.net.ssl.internal.ssl.Provider security.provider.3=com.safenetinc.luna.provider.LunaProvider security.provider.4=com.sun.rsajca.Provider security.provider.5=com.sun.crypto.provider.SunJCE security.provider.6=sun.security.jgss.SunProvider
You can set our provider in first position for efficiency if Luna HSM operations are your primary mode. However, if your application needs to perform operations not supported by the LunaProvider (secure random generation or random publickey verification, for example) then it would receive error messages from the HSM and would need to handle those gracefully before resorting to providers further down the list. We have found that having our provider in third position works well for most applications.
The modifications in the java.security file are global, and they might result in the breaking of another application that uses the default KeyPairGenerator without logging into the Luna Network HSM first. This consideration might argue for using dynamic registration, instead.
JSP Dynamic Registration
You might prefer to employ dynamic registration of Providers, in order to avoid possible negative impacts on other applications running on the same machine. As well, the use of dynamic registration allows you to keep installation as straightforward as possible for your customers.
This sample code shows an example of dynamic registration with the Luna provider. The Luna provider is registered in position 2, ensuring that the "SUN" provider is still the default. If you want the Luna provider to be used when no provider is explicitly specified, it should be registered at position 1.
try {
com.safenetinc.luna.LunaSlotManager.getInstance().login("<HSM Partition Password>");
java.security.Provider provider = new com.safenetinc.luna.provider.LunaProvider();
// removing the provider is only necessary if it is already registered
// and you want to change its position
java.security.Security.removeProvider(provider.getName());
java.security.Security.insertProviderAt(provider, 2);
com.safenetinc.luna.LunaSlotManager.getInstance().logout();
} catch (Exception e) {
System.out.println("Exception caught during loading of the providers: "
+ ex.getMessage());
Post-Installation Tasks
Making Private and Secret Keys Extractable
By default, all generated private and secret keys have their CKA_EXTRACTABLE attribute set to 0 (see Key Attribute Defaults). These keys are stored in the HSM hardware and cannot be extracted, only cloned to a partition on another HSM. This attribute cannot be modified later. If you want the ability to wrap private and/or secret keys and export them off the HSM, you must use one of the following two methods to set CKA_EXTRACTABLE to 1 (TRUE) when the key is created:
Global configuration:
Configure java.security as follows to have JSP create all future private/secret keys with CKA_EXTRACTABLE=1:
>To make all private keys extractable, add the following line to java.security:
com.safenetinc.luna.provider.createExtractablePrivateKeys=true
>To make all secret keys extractable, add the following line to java.security:
com.safenetinc.luna.provider.createExtractableSecretKeys=true
Local configuration:
Configure CKA_EXTRACTABLE on a key-by-key basis by using the following methods in your Java application:
>To make the next generated private key extractable using the LunaSlotManager.setPrivateKeysExtractable() method:
LunaSlotManager.getInstance().setPrivateKeysExtractable(true); // Set CKA_EXTRACTABLE=1 on upcoming private keys
kpg = KeyPairGenerator.getInstance("RSA", "LunaProvider");
kpg.initialize(2048);
myPair = kpg.generateKeyPair();
LunaSlotManager.getInstance().setPrivateKeysExtractable(false); // Set CKA_EXTRACTABLE=0 on upcoming private keys
NOTE To wrap and export private keys, the partition must have partition policy 1: Allow private key wrapping set to 1 (ON). See Cloning or Export of Private Keys.
>To make the next generated secret key extractable using the LunaSlotManager.setSecretKeysExtractable() method:
LunaSlotManager.getInstance().setSecretKeysExtractable(true); // Set CKA_EXTRACTABLE=1 on upcoming secret keys
kg = KeyGenerator.getInstance("AES");
kg.init(256);
aesKey = kg.generateKey();
LunaSlotManager.getInstance().setPrivateKeysExtractable(false); // Set CKA_EXTRACTABLE=0 on upcoming secret keys
Using Luna JCE/JCA with 64-bit Libraries
If you are using Luna JCE/JCA with the 64-bit libraries for Luna Network HSM, you must include the -d64 switch in the Java command-line.
java -d64 -jar jMultitoken.jar
For most 64-bit platforms, 64-bit is supported. Some 64-bit platforms support the option of running in 32-bit mode), as a backward compatibility feature.
NOTE Luna HSM Client 10.1.0 and newer includes libraries for 64-bit operating systems only.
If you use the 64-bit installation and do not use the -d64 command-line switch in your Java command lines, the system attempts (by default) to use the 32-bit library (which is not installed, because you installed 64-bit in this example...), and the result is an error message complaining about the kernel model.
Using ECC Keys for TLS with Java 7
For optimal Java performance when using Elliptic Curve keys to perform TLS with Java 7, where those keys reside in the HSM, you must configure the SunEC security provider (sun.security.ec.SunEC) to be below the LunaProvider in your java.security file.
We suggest that you not attempt to resolve a performance issue by having the LunaProvider as the default because that would result in the symmetric keys also being used in the HSM which is not optimal for performance.
Managing Security for Java Developers
The Luna JSP is a Java API that is intended to be used as an interface between customer-written or third-party Java applications and the Luna USB HSM 7. Managing security issues associated with the overall operational environment in which the application is running, including the user interface, is the responsibility of the application.
A common example would be input and capture of user name and password. The application, or a set of organizational procedures, is responsible for making the access control decision regarding whether the user has the necessary permissions (at the organizational level) to access the HSM's services and then must provide protection for the password as it is entered, and erasure from memory after the operation is completed. The Luna JSP will control access to the HSM based on the correct password being input from the application via the Login method, but security outside the HSM is your responsibility.
Non-standard ECDSA Mapping
The Luna provider maps the "ECDSA" signature algorithm to "NONEwithECDSA". The Java convention is to map it to "SHA1withECDSA". This is noted here in case you wish to use it in provider inter-operability testing. This mapping is noted in the Javadoc as well.
For comparison, "RSA" maps to "NONEwithRSA" while "DSA" maps to "SHA1withDSA".
Notes about thread safe, session safe, and multi-threading
PKCS#11 (the standard, and Thales's implementation) requires that a session can be used only by a single thread at a time. That is, multiple threads cannot access the same session simultaneously. Threads can share a session; however the application must ensure that only one thread accesses the session at a time. It is simpler for an application to assign a unique session for each thread, but applications do not need to follow that pattern.
Our LunaProvider endeavors to be thread safe in the way it uses our PKCS#11 library. But customer Java applications must follow the threading model defined by Java. For example, Java Cipher objects ( essentially all crypto-related objects) are not thread safe according to the JSP specification. Similar to PKCS#11 sessions, only one thread should use a cipher object at a time. Our LunaProvider requires that the Java application follows that JSP approach.
Therefore, it is very possible, and expected, to see sessions being used by multiple threads, all in legitimate and thread-safe ways according to both JSP and PKCS#11.
