Configure the SafeNet Luna SA HSM v5.4.1

This section describes how to install SafeNet Luna SA Hardware Security Module on the gateway. For information on using the Luna HSM, refer to the SafeNet Luna Getting Started Guide. For the compatible SafeNet Luna versions with the Gateway, see "Hardware Security Modules (HSM)" in .
This section describes the installation procedures for the SafeNet Luna SA Hardware Security Module on the
Layer7 API Gateway
. For information on using the Luna HSM, refer to the Requirements and Compatibility page.
If you're looking to...
  • Install version 7.2 of the client from scratch, go to this page.
  • Upgrade to version 7.2 from a previous version of the client (e.g., version 5.4.1), go to this page.
The client software on the Gateway machine must already have a partition that is assigned to it in the Luna HSM.
Step 1 - Install the Luna Client Software
  1. Use SCP to copy the Linux 64-bit SafeNet client files over to a temporary directory on the Gateway.
  2. While logged in as the
    root
    user, navigate to the directory on the Gateway containing the client files and then run the install script:
    # ./install.sh
  3. Accept the license and then select the product and components to install.
    1. For the product, select option
      1
      and then press
      n
      to continue.
    2. For the component, select options
      2
      to
      4
      and then press
      i
      to begin the installation.
Step 2 - Connect Client to a Partition
After the Luna client is installed, the next step is to connect it to the Luna partition. The following assumes that DNS is used.
(1) This procedure requires access to the Luna appliance admin password (available from your Luna administrator). (2) CA Technologies recommends that each Gateway cluster be assigned its own Luna partition for its exclusive use.
To connect the Luna client to a partition
:
  1. Navigate to the Luna SA command directory:
    # cd /usr/safenet/lunaclient/bin
  2. Copy the Luna appliance server certificate to the client:
    # scp [email protected]<LunaBoxHostname>:server.pem .
  3. Register the server with the client:
    # ./vtl addServer -n <LunaBoxHostname> -c server.pem
  4. Generate a client certificate:
    # ./vtl createCert -n <ClientHostname>
  5. Copy the client certificate to the server:
    # scp /usr/safenet/lunaclient/cert/client/<ClientHostname>.pem [email protected]<LunaBoxHostname>:
  6. Log in to the Luna HSM appliance to register the client with the server, then assign the client to a server partition:
    # ssh [email protected]<lunaboxhostname> lunash:> client register -client <ClientHostname> -hostname <ClientHostname> lunash:> client assignPartition -client <ClientHostname> -partition <GatewayPartition>
  7. Run the following command only if the hostname is not resolvable:
    lunash:> client hostip map -client <ClientHostname> -ip
  8. Log out from the Luna HSM:
    lunash:> exit
  9. Set the read permissions for the certificate files in the following directories:
    # chmod a+r /usr/safenet/lunaclient/cert/server/*.pem # chmod a+r /usr/safenet/lunaclient/cert/client/*.pem
  10. Verify that the client is connected to its assigned partition:
    # ./vtl verify
    When the verification is successful, the Luna slots partitions are displayed.If the verification is unsuccessful, edit the file
    Chrystoki.conf
    within the /etc directory and then try again. The setting should be disabled, as shown:
    Misc = { PE1746Enabled = 0; }
  11. Run the following command to verify that your token client PIN is correct for this partition and that the partition is empty:
    # ./cmu list
    Enter the partition password and follow the instructions on the Luna PED pad. If the verification is successful, you see a display similar to the following back on the command line:
    nExitCode returned was =0 Please enter password for token in slot 1 : ******************* handle=9 label=root.ame2.l7tech.com handle=11 label=root.ame2.l7tech.com--cert0 handle=30 label=SSL--cert0 handle=32 label=SSL handle=48 label=hmm--cert0 handle=49 label=hmm handle=55 label=ame2.l7tech.com--cert0 handle=56 label=ame2.l7tech.com handle=121 label=peanuts--cert0 handle=128 label=ssl_x4150upgrade handle=130 label=ssl_x4150upgrade--cert0 handle=133 label=peanuts handle=175 label=ca handle=180 label=caec handle=183 label=caec--cert0 handle=189 label=ca--cert0 handle=266 label=test--cert0 handle=269 label=test handle=296 label=testca handle=298 label=testca--cert0 handle=308 label=peanuts2 handle=310 label=peanuts2--cert0 handle=419 label=NEWSSL--cert1 handle=432 label=NEWSSL--cert0 handle=495 label=peanuts2_ca handle=503 label=peanuts2_ca--cert0
Step 3 - Configure the JDK
The final step involves copying the .JAR files from the 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.createExtractableKeys=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
. Do one of the following:
  • If you are accessing the Gateway using the Policy Manager (either browser or desktop client) over the default ports 8443/9443, follow both
    "To reset the default list"
    and
    "To enable SafeNet Luna"
    below.
  • If you are accessing the Gateway only using the browser client over a custom port, follow
    "To enable SafeNet Luna"
    only.
To reset the default list
:
The following procedure corrects an issue that may occur when using the Policy Manager browser client over the default ports.
  1. Start the Policy Manager
    desktop
    client and connect to the Gateway. Alternatively, you may use the browser client over port 8443.
  2. Run the Manage Listen Ports task.
  3. Select port
    9443
    and then click [
    Properties
    ].
  4. Select the [
    SSL/TLS Settings
    ] tab.
  5. Click [
    Use Default List
    ] and then click [
    OK
    ] to close the dialog box.
Repeat the steps above for port
2124
if the Gateway continues to show a "starting" status.
To enable SafeNet Luna
:
  1. Run the Manage Private Keys task.
  2. Click [
    Manage Keystores
    ] to display the Manage Keystore dialog.
  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 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 CA API Gateway will be the preferred platform to perform cryptographic operations using keys retrieved from the Luna HSM.
  5. Restart the Gateway.
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.