Configure the SafeNet Luna SA HSM v7.2

This section describes how to install SafeNet Luna SA Hardware Security Module v7.2 on the
Layer7 API Gateway
. If you are looking to install client v5.4.1 of this module, please refer to this page. If you are performing an upgrade of your Luna client, you’ll need to uninstall v5.4.1 before installing v7.2 as described here. For information on using the Luna HSM, refer to SafeNet Luna documentation.
For the compatible SafeNet Luna versions with the Gateway, see "Hardware Security Modules (HSM)" in Requirements and Compatibility.
Luna Partition Policy Modifications Available for Luna SA HSM v7.2 Users
Beginning with Gateway version 10.0 CR 2, Layer7 has rolled out the first phase of the new option to turn on or off a select number of Luna partition policies to suit their enterprise security requirements while connected to the API Gateway.
Policy #2: 'Enable Private Key Unwrapping'
As of Gateway version 10.0 CR 2, you can turn OFF 'Policy 2: Enable private key unwrapping' (Luna HSM default value is ON) to ensure that public/private key pairs are created and stored within the Luna HSM without impacting the general operation of the Gateway.
To ensure that the Gateway can continue to route and secure API traffic after installing the patch for version 10.0 CR 2, the following configuration changes must be made to a Luna HSM that is running in FIPS mode:
  1. Open the
    /etc/Chrystoki.conf configuration file.
  2. Add the
    RSAKeyGenMechRemap=1;
    line to the 'Misc' section. For example:
    Misc = { PE1746Enabled = 0; ToolsDir = /usr/safenet/lunaclient/bin; PartitionPolicyTemplatePath = /usr/safenet/lunaclient/data/partition_policy_templates; ProtectedAuthenticationPathFlagStatus = 0;
    RSAKeyGenMechRemap=1;
    }
There are four parts to the configuration of the Luna SA HSM client:
For the first two steps (i.e., client installation 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.
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 sh 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 sa -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.
About the HSMUSERS Group
The client installation also automatically creates the hsmusers group, allowing non-root users who are members of that group to access the HSMs and partitions attached to the Gateway. In order for the Gateway to work with the HSM, you must add the ‘gateway’ user to that group.
To add the ‘gateway’ user to the hsmusers group, enter the following command:
gpasswd --add gateway hsmusers
For more instructions on adding other users to the hsmusers group, removing users from the hsmusers group, and detailed effects of adding and removing users to and from the group, please consult Thales SafeNet Luna documentation under ‘Linux SafeNet Luna HSM Client Software Installation’.
Step 2 - 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, Thales has offered a single-step procedure that installs and configures the Luna partition(s) – We strongly recommend that you reference Luna documentation (See ‘Creating a Network Trust Link – One-step Setup’) in conjunction with the procedure to connect the Luna client to a partition as described in the Luna SA HSM v5.4.1 configuration instructions here.
Ensure your installation meet all the prequisites 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 under ‘Creating an NTLS Link Between a Client and a Partition’.
Step 3 - Configure the JDK
After installing the Luna client, several SafeNet .JAR library files are made available for the Gateway to use.
The third step involves copying the .JAR files from the Luna JSP into the JDK (Java Development Kit) for the Gateway appliance.
To configure the JDK for the Gateway
:
  1. Navigate to the following directory on the Gateway:
    # cd /usr/safenet/lunaclient/jsp/lib
  2. Copy the Luna .JAR files over to the Gateway:
    # cp libLunaAPI.so Luna*.jar /opt/SecureSpan/JDK/jre/lib/ext
  3. Set the file permissions for the JDK library as follows:
    # chmod a+r /opt/SecureSpan/JDK/jre/lib/ext/*Luna*
  4. Open the following file in a text editor:
    /opt/SecureSpan/JDK/jre/lib/security/java.security
  5. Add the following line to the file and then save and close the file:
    com.safenetinc.luna.provider.createExtractablePrivateKeys=true com.safenetinc.luna.provider.createExtractableSecretKeys=true
  6. Set the file permissions for the Luna client as follows:
    # chmod -R 655 /usr/safenet
  7. 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
    [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.
  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.