SafeNet JSP Overview and Installation

The SafeNet JSP is part of an application program interface (API) that allows Java applications to make use of certain SafeNet products.

As with other APIs, some existing Java-based applications might have generic requirements and calls that can already work with SafeNet 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 SafeNet 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 SafeNet Java API usage notes for developers, as well as development support by SafeNet. A standard Java development environment is required, in addition to the API provided by SafeNet.

Please refer to the current-version SafeNet Luna PCIe HSM Customer Release Notes (CRN) for the most up-to-date list of supported platforms and APIs.

JDK Compatibility

We formally test SafeNet Luna PCIe HSMs and our Java provider with SUN JDK for all platforms except AIX, and with IBM JDK for the AIX platform. We have not had problems with OpenJDK, although it has not been part of our formal test suite. The SafeNet JCE provider is compliant with the JCE specification, and should work with any JVM that implements the Java language specification.

Occasional problems have been encountered with respect to IBM JSSE.

GNU JDK shipped with most Linux systems has historically been incomplete and not suitable.

Installation

To use the SafeNet JavaSP service providers four main components are needed.

Java SDK

The SafeNet JSP supports the following Java versions:

>Oracle Java 7/8/9/10/11

>OpenJDK 7/8/9/10/11

>IBM Java 7/8

First, acquire and install the JDK or JRE (available from the Java site, not included with the SafeNet software). Java must be installed before the SafeNet software, as some of the Java files must be manipulated as described in the JSP portions of the Getting Started section of this Help.

Java Cryptographic JCE Policy files (optional)

If you intend to generate large key sizes, you will need two cryptographic JCE Policy files v 7/8/9/10/11 (available from the Java web site). The Getting Started section of this Help has instructions on what to do with the two files (local_policy.jar and US_export_policy.jar).

If you see errors like "Invalid Key size", that is usually an indication that the JCE is not properly installed.

SafeNet Luna HSM Client

Follow the installation procedure for the SafeNet Luna HSM Client as described in the Installation Guide.

SafeNet JavaSP

When installing the SafeNet Luna Client software, also choose the option to install SafeNet JSP. Instructions are provided in the platform-specific pages, including instructions for installing SafeNet JSP for each operating system (files to copy/replace, editing to perform, etc.) so that SafeNet Luna PCIe HSM and SafeNet JSP can work with the JRE.

Notes about thread safe, session safe, and multi-threading

PKCS#11 (the standard, and Gemalto'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.

Post-Installation Tasks

Extractable Private and Secret Keys

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 Keys In Hardware vs. Private Key Export in the Administration 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 SafeNet JCE/JCA with 64-bit Libraries

If you are using SafeNet JCE/JCA with the 64-bit libraries for SafeNet Luna PCIe HSM, you must include the "-d64" switch in the Java command-line.

For example: 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.

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.

A Security Note for Java Developers

The SafeNet JSP is a Java API that is intended to be used as an interface between customer-written or third-party Java applications and the SafeNet Luna PCIe 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 SafeNet 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

The SafeNet 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".