Configure the SafeNet Luna HSM Client v10.2

This topic summarizes the general steps needed to perform a fresh installation of the SafeNet Luna HSM Client v10.2 (i.e., the Luna Universal Client) on a Gateway machine.
Gateway version 10.1 Users
Luna HSM users who plan to upgrade to Gateway version 10.1 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
For three of the outlined steps (i.e., client installation, patch application, and partition connection), 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.
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.
The remainder of this page will focus on areas of the configuration that are specific or unique to the Gateway.
Files Required
This installation 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
Stop the Gateway
Stop the Gateway from running with the following command:
# service ssg stop
Optional: Uninstall a Previous Version of the Luna Client Software
If you have a previous version of the Luna client installed, you must uninstall it before installing version 10.2 of the client.
Go to the following client installation directory:
/usr/safenet/lunaclient/bin
Run the following script:
# uninstall.sh
Step 1 - Install the Luna Client Software
  1. 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 client software with the following components:
    • Luna JSP (Java API for interfacing between the Gateway and the Luna HSM)
    • Luna JCPROV (Java wrapper)
  2. Set the file permissions for the Luna client as follows:
    # chmod -R 655 /usr/safenet
  3. Add
    gateway
    user to the hsmusers group:
    # gpasswd --add gateway hsmusers
  4. Verify
    gateway
    is a group member:
    # lid -g hsmusers
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.1'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 directory:
    # cp <patch-directory>/linux/64/libLunaAPI.so /opt/SecureSpan/Gateway/runtime/lib/ext
    # cp <patch-directory>/LunaProvider.jar /opt/SecureSpan/Gateway/runtime/lib/ext
  4. Set the file permissions for the Luna files as follows:
    # chown layer7:layer7 /opt/SecureSpan/Gateway/runtime/lib/ext/*Luna*
    # chmod a+r /opt/SecureSpan/Gateway/runtime/lib/ext/*Luna*
Step 3 - Configure Java Virtual Machine Settings
In this step, you'll define the path for the Java Virtual Machine to load Luna-related libraries from via the node.properties file.
To configure the node.properties file
:
  1. Open and edit the following node.properties file found in the following location:
    # vi /opt/SecureSpan/Gateway/node/default/etc/conf/node.properties
  2. Ensure that the following property and value are appended to the node.properties file:
    node.java.opts=-Djava.library.path=/opt/SecureSpan/Gateway/runtime/lib/ext
  3. Save the changes you've made to the node.properties file.
Step 4 - Connect Luna Client to the HSM and Partition
Your Appliance/OVA Gateway uses cryptographic technology provided by the HSM appliance to create a secure Network Trust Link (NTL) between the Luna client, installed on your Gateway appliance, and the Luna appliance module. You'll also need to configure links between the client and individual partitions on the HSM appliance.
(1) This procedure requires access to the Luna appliance admin password (available from your Luna administrator). (2) Broadcom Layer7 recommends that each Gateway cluster be assigned its own Luna partition for its exclusive use.
Since the release of v7.2 (and subsequent releases) of the Luna SA HSM client, Thales has offered a single-step procedure that installs and configures the Luna partition(s) – We strongly recommend that you reference Luna SA HSM documentation (See the 'Creating an NTLS Connection' sections) in conjunction with the procedure to connect the Luna client to a partition as described in current Luna SA HSM documentation.
Ensure your installation meets all the prerequisites as defined by Thales in their documentation for the SafeNet Luna Network HSM and the client side (your Gateway server).
For more detailed instructions and guidance on how to verify your HSM-client setup and information on connection limits, please reference Thales Luna documentation.
Step 5 - Enable SafeNet Luna on the Gateway
To enable SafeNet Luna
:
  1. Start the Gateway:
    # service ssg start
  2. Run the Manage Private Keys task.
  3. 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”.
  4. Click [
    Enable SafeNet HSM
    ]. The "Current keystore type" should now display "SafeNet HSM".
    The Connect to SafeNet HSM window appears.
  5. Enter a
    Partition Label
    , the accompanying
    Partition Password
    , and then click
    [Connect]
    .
    Finding the Partition Label
    On the Gateway server or your Luna client machine, navigate to the
    /usr/safenet/lunaclient/bin
    directory and enter the LunaCM
    slot list
    command. The response returned should list all the partitions assigned to the Luna HSM client.
    Optional
    : 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.
Step 6 - Configure ssg.security
The ssg.security file allows you to override current settings in the java.security file.
To configure the ssg.security file
:
  1. Open the following configuration file in a text editor:
    /opt/SecureSpan/Gateway/runtime/etc/ssg.security
  2. For a default partition setup for your Luna HSM, ensure the following order is configured in the file:
    security.provider.1=SUN security.provider.2=SunJCE security.provider.3=SunJGSS security.provider.4=SunSASL security.provider.5=XMLDSig security.provider.6=SunPCSC security.provider.7=JdkLDAP security.provider.8=JdkSASL security.provider.9=SunPKCS11 security.provider.10=com.safenetinc.luna.provider.LunaProvider security.provider.11=SunRsaSign security.provider.12=SunEC security.provider.13=SunJSSE
    If you are planning to use the default Luna partition policy settings, ensure the following two lines are included in the ssg.security file:
    com.safenetinc.luna.provider.createExtractablePrivateKeys=true com.safenetinc.luna.provider.createExtractableSecretKeys=true
    If you plan to use a different partition policy setting, see Modify Luna Partition Policies  for instructions on how to configure the ssg.security file.
Step 7 - Delete Artifacts from a Previous Installation of the Luna HSM Client
If you have a previous installation of the Gateway and Luna HSM client, artifacts from that previous installation should be removed to ensure proper keystore operation of the Luna HSM. Ensure the following directory is deleted:
/opt/SecureSpan/JDK/jre/
The directory may contain artifacts from a previous client installation such as
LunaProvider.jar
and
nCipherKM.jar
- these files can be deleted along with the directory.
Restart your Gateway after deleting the directory and artifacts.
Step 8 - Restart the Gateway and Confirm HSM is Connected
Restart the Gateway for the connection to take effect.
# service ssg restart
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.