Configure nShield Connect for the Software Gateway

This page describes the configuration steps needed to set up the nShield Connect Connect XC HSM to work with the software form-factor of the Gateway. With this setup, you may use the nShield Connect XC HSM as the keystore in place of the Gateway SSG database. The integration with nShield Connect XC HSM for the software form-factor of the Gateway is available as of Gateway Version 10 CR1.
If you're looking to set up an nShield HSM for the appliance form-factor of the API Gateway, see here.
Legal Disclaimer
The acquisition and compilation of the nShield driver provided by nShield is at Customer's sole discretion and entirely subject to the terms of that third-party provider.
Don't Forget to Consult nShield HSM Documentation
For the most current vendor information on nShield Connect XC HSM setup, it's strongly recommended that you refer to the technical documentation that came packaged with your nShield HSM. The nShield-derived instructions provided on this page are meant to provide general guidance for Gateway users only. For nShield product-specific questions, please contact Entrust support.
3
Step 1: Fulfill Prerequisites
Ensure that all prerequisites have been fulfilled prior to installing Layer7-supplied files and scripts on the Gateway machine for nShield HSM configuration. There are three parts to the prerequisites:
Gateway Version, Operating System, and Libraries
Before you attempt to configure the nShield Connect HSM to work with your software API Gateway, ensure that the following items are installed, configured and/or available beforehand:
Category
Description
Software/Hardware Version
Available as of Version 10 CR1 for the software Gateway.
For the release of version 10 CR1, the software Gateway was tested against the nShield Connect XC HSM device with the following specifications:
  • HSM Firmware Version 12.50.11
  • nFast Client Software Version 12.60.7
Operating System
Your software Gateway must be installed on one of the following Operating Systems:
  • CentOS 7 or 8
  • RHEL 7 or 8
The software Gateway should be installed in the
/opt/SecureSpan/
folder.
Libraries
Ensure the following libraries are installed:
  • Perl Core
  • Libnsl (Required only for CentOS/RHEL 8.x)
Java
AdoptOpenJDK 1.8.0 8u252-b09
See other system requirements for the software Gateway here.
Security World Client Software
Ensure that nShield Security World client software has been installed on the machine hosting the Gateway, per the instructions outlined in the nShield user documentation. Perform these steps prior to setting up your physical nShield HSM device.
  • Ensure that AdoptOpenJDK is installed in the
    /usr/bin
    folder as required by the Gateway. To do this, manually insert a soft link to the actual java location with the following command:
    ln -s /<JAVA FOLDER>/bin/java /usr/bin/java
  • Ensure that port 9004 is made available for the nShield Connect HSM and if applicable, a Remote File System (RFS).
  • After the required Security World tar files are extracted, a new
    /opt/nfast/
    will be created.  When nShield Connect HSM Setup is completed, installed Security World files should be found in the
    /opt/nfast/kmdata/local
    folder.
  • After running the nShield install script, two user names/groups are created: nfast and ncsnmpd
    • Ensure that 'gateway' and 'layer7' users are added to the nfast group:
      usermod -a -G nfast gateway usermod -a -G nfast layer7
  • JAR file requirement: Ensure that nCipherKM.jar is present in the JAVA_HOME/jre/lib/ext folder. This JAR file enables the Java interface for the HSM. If it is not there, copy the file from
    /opt/nfast/java/classes/nCipherKM.jar
    .
nShield Connect HSM Setup
This section describes the configurations you'll need to perform directly on the nShield Connect HSM and RFS server before configuring the nShield Connect as your keystore on your Gateway machine:
It's strongly recommended that you create and configure a stand-alone RFS server to store and manage encrypted key files and to not use the software Gateway as both a client and RFS server. The Gateway should only be configured as a client to the HSM.
For these nShield-specific tasks, including the setting up of a Remote File System (RFS), consult your nShield technical documentation for the latest instructions.
Create the Security World
If you haven't done so already, you'll need to create a new security world on your Connect XC HSM device. You'll also need to install and use the 'New-World' utility on a privileged RFS.
Configure the Gateway as a Client
Next, you'll need to configure the API Gateway as a client to the nShield Connect XC HSM.
Consult your provided nShield technical documentation to learn how to:
  • Create a new nfast client (the API Gateway) from the nShield HSM
  • Perform the following in the API Gateway client machine:
    • Retrieve nShield ESN and keyhash information on the API Gateway client machine.
    • Configure TCP Sockets for Java applications.
    • Change ownership of
      /opt/nfast/kmdata/config/config
      .
Synchronize the Gateway Client with the RFS Server
After you've completed configuring the Gateway as a client, synchronize the Gateway with the RFS server. Again, it's strongly recommended that you use a stand-alone RFS Server that's separate from the Gateway client machine.
Consult your provided nShield technical documentation to learn how to:
  • Allow the nfast client (API Gateway client) access on the RFS machine.
  • Set up synchronization with the RFS machine and update RFS files on the API Gateway client.
  • Set up the appropriate ownership and permission settings for synchronization.
Step 2: Upgrading to Version 10 CR1 - Locate the nShield Connect TGZ File
After you've you performed all the required prerequisite system checks and steps, locate the 'ssg-nshield-10.0.00.10675-CR01.tar.gz' tarball file that is packaged with 10-CR01.zip (download from the Support Portal here). This tarball file contains all the files required for the nShield Connect HSM to work with the API Gateway.
Step 3: Extract the Layer7 nShield Configuration Files to the Gateway Machine and Update Permissions
  1. Copy the 'ssg-nshield-10.0.00.10675-CR01.tar.gz' tarball file to your Gateway machine and extract its contents.
  2. Ensure that the following files are moved to the
    /opt/SecureSpan/Gateway/runtime/bin/
    folder:
    • envclean
    • ncipherconfig.pl
    • ssgconfig_launch
    • hsm.sh
  3. Complete the installation by changing permissions and ownership group for the following files:
    • Change the file permission to 555.
      chmod 555 hsm.sh chmod 555 envclean chmod 555 ncipherconfig.pl chmod 555 ssgconfig_launch
    • Change the ownership group to layer7.
      chown layer7:layer7 hsm.sh chown layer7:layer7 envclean chown layer7:layer7 ncipherconfig.pl chown layer7:layer7 ssgconfig_launch
Step 4: Configure the nShield HSM on the Software Gateway
Before configuring your software Gateway with the nShield Connect HSM, stop any running Gateways.
/opt/SecureSpan/Gateway/runtime/bin/gateway.sh stop
  1. To view the software Gateway HSM configuration menu, run hsm.sh.
    /opt/SecureSpan/Gateway/runtime/bin/hsm.sh
    The following software Gateway configuration menu appears:
    CA API Gateway Software configuration menu. What would you like to do? 1) Manage HSM X) Exit Please make a selection:
  2. Press 1 on your keyboard.
    The following nShield HSM configuration menu appears:
    This menu allows you to configure the nShield Hardware Security Module on the Layer7 API Gateway What would you like to do? 1) Manage Gateway nShield HSM status 2) Use manually-programmed security world X) Exit menu Please make a selection (X to exit):
  3. Press 2 on your keyboard to continue the HSM configuration process. The system verifies that the required security world files are present in the
    /opt/nfast/kmdata/local
    folder and configures the nShield keystore.
  4. Press the Enter key on your keyboard to continue.
    After the HSM configuration is completed, the following HSM status management menu is shown:
    What would you like to do? 1) Enable Gateway use of the nShield HSM 2) Disable Gateway use of the nShield HSM X) Exit menu
    Optional
    : You may also disable the use of the nShield HSM for an already nShield HSM-enabled Gateway in this menu by pressing the 2 key. However, before disabling HSM use, you must stop the Gateway first. To re-enable nShield HSM use, repeat steps 1 to 2 to get to the nShield HSM configuration menu. From that menu, press 1 on your keyboard to access this HSM status management menu to see the enable/disable options.
  5. Press 1 on your keyboard to enable Gateway use of the configured nShield HSM and finalize the setup.
Step 5: Run the Software Gateway with nShield HSM
Start the Gateway with the following command:
/opt/SecureSpan/Gateway/runtime/bin/gateway.sh start
Troubleshooting
The following is a collection of common errors and fixes related to the Gateway configuration of the nShield Connect HSM.
'Fatal.pm' Error When Running hsm.sh
Error Message:
Can't locate Fatal.pm in @INC (you may need to install the Fatal module) (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at /opt/SecureSpan/Gateway/runtime/bin/ncipherconfig.pl line 21. BEGIN failed--compilation aborted at /opt/SecureSpan/Gateway/runtime/bin/ncipherconfig.pl line 21
Fix: This error is a result of missing Perl libraries. Run the following command:
yum install perl-core
'Java not found' Error When Running hsm.sh
Error Message:
Java not found
Fix: This error is occurs when the hsm.sh script can't find the required java soft link in
/usr/bin/java
. If you are missing the soft link to the java installation, use the following command to create it:
ln -s /<JAVA FOLDER>/bin/java /usr/bin/java
For the configuration of the nShield Connect HSM, do not use
<JAVA FOLDER>/jre/bin/java
when creating the soft link to the java installation. Use
<JAVA FOLDER>/bin/java
.