Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Configure the SafeNet Luna SA HSM

Last update November 28, 2018

This section describes how to install SafeNet Luna SA Hardware Security Module on the CA API 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 Requirements and Compatibility.

Note: 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:

    # ./
  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.

Notes: (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 admin@<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 admin@<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 admin@<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 <ClientIP>

  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=30       label=SSL--cert0
    handle=32       label=SSL
    handle=48       label=hmm--cert0
    handle=49       label=hmm
    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 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:
  5. Add the following line to the file and then save and close the file:


    If your Luna machine has FIPS mode enabled, insert an additional line to the file as follows:

  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 theCA 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.

Tip: 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".
  4. Enter the Gateway partition password when prompted.
  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.
Note: 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.
Was this helpful?

Please log in to post comments.