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 Cloud HSM Customer Release Notes (CRN) for the most up-to-date list of supported platforms and APIs.

This following sections describe the tasks required to set up the JSP API:

>Installation

>JSP Registration

>Post-Installation Tasks

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 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 HSM Client

Follow the installation procedure for the HSM Client as described in the Installation Guide. There are two SafeNet files: the LunaProvider.jar file, and the Java library file (libLunaAPI.so in Unix based systems or LunaAPI.dll in Windows systems). To ensure that the Java Environment can find these files, follow the instructions for either Java 7/8 or Java 9+.

Operating System	JSP Install directory
Linux	><untar_location>/jsp/LunaProvider.jar ><untar_location>/jsp/64/libLunaAPI.so
Windows	><unzip_location>\LunaProvider.jar ><unzip_location>\LunaAPI.dll

To configure Java 7/8 for Luna JSP

To ensure that Luna Cloud HSM 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 , any application would be able to use Luna product without being designed to log in to the HSM Partition.

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 keys off the HSM, the service provider must have enabled the private key wrapping feature when your partition was created, and the partition must have partition policy 1: Allow private key wrapping set to 1 (ON). See About Key Cloning and Key Wrapping in the Cryptovisor Client User Guide.

>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 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 Cloud HSM. 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.