Upgrading the SafeNet Luna SA HSM Client from v7.2 to v10.2

This topic describes the upgrade process from v7.2 to v10.2 (i.e., the Luna HSM Universal Client) of the Luna HSM client for users of the API Gateway version 10.0 CR 3 or newer and Luna SA HSM. Luna SA HSM users MUST upgrade their HSM client to v10.2 if they plan to upgrade to API Gateway version 10.0 CR 3 or newer.
The following information assumes that you are upgrading from Luna HSM client version 7.2 to version 10.2 for the
Layer7 API Gateway
to work with your Luna HSM appliance. Unlike previous client upgrade procedures that require an uninstall of an older client followed by a fresh install of a newer client, this procedure has additional steps to fulfill a 10.0 CR 3 or newer API Gateway upgrade and Java-related patch requirement.
Gateway version 10.0 CR 3+ Users
Luna HSM users who plan to upgrade to Gateway version 10.0 CR 3 or newer or higher MUST upgrade their Luna HSM client to version 10.2.
About Luna HSM Client Procedures
The information on this page and any other CA Broadcom page regarding Luna HSM client configuration is derived from Thales documentation and is intended to provide a quick reference for
Layer7 API Gateway
customers that require integration with the Luna HSM product. Thales is a third-party vendor and is not affiliated with Broadcom Layer7. If and whenever possible, We strongly recommend that you consult Thales' Luna HSM product documentation for comprehensive end-to-end guidance on the installation or configuration of the Luna HSM and its associated client software.
Before You Begin
This upgrade procedure requires two third-party files from Thales.
  • Go to this Thales page to download the Luna HSM Universal Client v10.2.
  • Contact Thales support at https://supportportal.thalesgroup.com to retrieve the following patch file: 630-000419-001_SW_Patch_jsp_fix_jdk11_UC_Clnt_10.2.0_Custom_Release.zip
Part 1 - Disable the SafeNet HSM Keystore First
Prior to performing the following steps, ensure that SafeNet HSM is disabled as a keystore in the Policy Manager's Manage Keystore function. After disabling, stop or restart the Gateway so that the Gateway will default back to 'Software DB' as the keystore.
Part 2 - Perform the API Gateway 10.0 CR 3+ Upgrade
After you've disabled your SafeNet HSM keystore, perform the patching process to upgrade your API Gateway to version 10.0 CR 3 or newer as outlined in Patch an Appliance Gateway. Skip this part if you've already upgraded to version 10 CR 3 or newer of the API Gateway.
Part 3 - Stop the Gateway
Stop the Gateway from running with the following command:
# service ssg stop
Part 4 - Uninstall Luna Client Software
Go to the following client installation directory:
Run the following script:
# uninstall.sh
Part 5 - Install and Configure the Luna SA HSM Client v10.2
There are four major steps to the configuration of the Luna SA HSM Universal Client (v10.2):
For client installation instructions we strongly recommend that you follow the existing SafeNet Luna product documentation that should have come with your appliance purchase. This ensures that you’ll be following all the latest hardware-specific instructions and recommendations directly from the vendor.
The remainder of this page will focus on areas of the configuration that are specific or unique to the Gateway.
When performing any configuration or installations related to the Luna client on the Appliance form-factor of the Gateway, you must be logged in as a ‘root user’ in your Linux OS.
Step 1 - Install the Luna Client Software
Thales has documented several options for installing the client, including their standard installation script (install.sh) and optional Java configuration instructions. For the majority of Luna-Gateway customers, the script-only installation method should be sufficient.
Use the following script, derived from Thales, to install the required Luna products and components for the
Layer7 API Gateway
sh install.sh -p network -c jsp -c jcprov
Running this script shall install the SafeNet Luna HSM product and the following components:
  • Luna JSP (Java API for interfacing between the Gateway and the Luna HSM)
  • Luna JCPROV (Java wrapper)
If you need to install other Luna products or components in addition to Gateway requirements, please reference Luna documentation.
Step 2 - Apply the Luna Client Patch
To apply the Luna client patch:
  1. Retrieve the 630-000419-001_SW_Patch_jsp_fix_jdk11_UC_Clnt_10.2.0_Custom_Release.zip patch file from Thales Technical Support. This client patch allows Luna HSM client v10.2 to work with API Gateway version 10.0 CR 3's JDK requirements.
  2. Unzip the patch file to reveal the following Luna jar and shared library files:
    • LunaProvider.jar
    • libLunaAPI.so
  3. Copy the jar and shared library file to the following two directories:
    cp libLunaAPI.so Luna*.jar /opt/SecureSpan/JDK/jre/lib/ext/ cp libLunaAPI.so Luna*.jar /usr/safenet/lunaclient/jsp/lib/
  4. Set the file permissions for the JDK library as follows:
    # chmod a+r /opt/SecureSpan/JDK/jre/lib/ext/*Luna*
Step 3 - Configure java.security
After installing the Luna client, and making SafeNet .JAR library files available for the Gateway to use, you'll need to configure the java.security file next.
To configure the java.security file
  1. Open the following file in a text editor:
  2. Take one of the following actions on the java.security file:
    • For a default partition setup for your Luna HSM, ensure the following order is configured in the file:
      security.provider.1=sun.security.provider.Sun security.provider.2=com.sun.net.ssl.internal.ssl.Provider security.provider.3=com.sun.crypto.provider.SunJCE security.provider.4=sun.security.jgss.SunProvider security.provider.5=com.sun.security.sasl.Provider security.provider.6=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.7=sun.security.smartcardio.SunPCSC security.provider.8=com.safenetinc.luna.provider.LunaProvider security.provider.9=sun.security.ec.SunEC security.provider.10=sun.security.rsa.SunRsaSign
    • If you are turning partition policies #2,5,6,17, and 33 off (see Modify Luna Partition Policies), ensure the following order is configured in the file:
      security.provider.1=sun.security.provider.Sun security.provider.2=sun.security.ec.SunEC security.provider.3=com.sun.net.ssl.internal.ssl.Provider security.provider.4=com.sun.crypto.provider.SunJCE security.provider.5=sun.security.jgss.SunProvider security.provider.6=com.sun.security.sasl.Provider security.provider.7=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.8=sun.security.smartcardio.SunPCSC security.provider.9=com.safenetinc.luna.provider.LunaProvider security.provider.10=sun.security.rsa.SunRsaSign
    If you are planning to use the default Luna partition policy settings, ensure the following two lines are included in the java.security file:
    com.safenetinc.luna.provider.createExtractablePrivateKeys=true com.safenetinc.luna.provider.createExtractableSecretKeys=true
    If you are planning to turn policies #2,5, 6, 17, and 33 off, do NOT add these two lines.
  3. Set the file permissions for the Luna client as follows:
    # chmod -R 655 /usr/safenet
  4. Restart the Gateway:
    service ssg restart
Step 4 - Enable SafeNet Luna on the Gateway
At this point, you may now enable the SafeNet Luna HSM on the
Layer7 API Gateway
To enable SafeNet Luna
  1. Run the Manage Private Keys task.
  2. Click [
    Manage Keystores
    ] to display the Manage Keystore dialog. Current keystore type is “System Default” and SafeNet HSM support should be indicated as “Ready to Use”.
  3. Click [
    Enable SafeNet HSM
    ]. The "Current keystore type" should now display "SafeNet HSM".
    The Connect to SafeNet HSM window appears.
  4. Enter a
    Partition Label
    , the accompanying
    Partition Password
    , and then click
    Finding the Partition Label
    On the Gateway server or your Luna client machine, navigate to the
    directory and enter the LunaCM
    slot list
    command. The response returned should list all the partitions assigned to the Luna HSM client.
    : Select the
    Prefer to use this device for all cryptographic operations
    option to ensure that all cryptographic operations are performed on the Luna HSM appliance itself. Otherwise, if left unselected, the
    Layer7 API Gateway
    will be the preferred platform to perform cryptographic operations using keys retrieved from the Luna HSM.
  5. Restart the Gateway for the connection to take effect.
You can confirm that the SafeNet Luna HSM is in effect by doing any of the following:
  • Under the Manage Private Keys task, check that the default SSL key shows location "SafeNet HSM".
  • When creating a new private key, the location should be "SafeNet HSM".
  • You should be unable to export a private key.
If the SafeNet Luna HSM is enabled but the Gateway is unable to connect to it on startup, the Gateway falls back to the software keystore.