Configure the nShield Connect

The gateway can use the nShield Connect family of HSMs (Hardware Security Modules) from nCipher as the keystore.
gateway10
These instructions apply to nShield Connect+ and nShield Connect XC HSMs.
The
Layer7 API Gateway
can use the nShield Connect family of HSMs (Hardware Security Modules) from nCipher as the keystore.
This topic describes:
  • How to set up the nShield Connect
  • How to switch between using the nShield Connect or the internal Gateway database as the keystore.
You cannot connect a nShield Connect appliance to a Gateway appliance that is already equipped with an internal HSM.
2
2
Before You Begin
Ensure that the following pre-conditions exist before configuring the nShield Connect.
  • The Gateway appliance must not have an internal HSM. You cannot connect an nShield Connect appliance to a Gateway appliance that already uses an internal HSM.
  • The
    ssg-nshieldpci
    RPM must be installed.
    To verify, run the following command:
    # rpm -qa | grep ssg-nshieldpci
    The version of the nShield RPM is returned if the RPM is installed correctly.
  • The
    layer7
    and
    gateway
    users are in the nfast group.
    To verify, run the following command:
    # egrep -i "^nfast" /etc/group
    Look for the response:
    nfast:x:502:gateway,layer7
    If either the
    gateway
    or
    layer7
    user is missing from the group, run the appropriate command below to add the missing user:
    # usermod -g layer7 -G 'layer7,nfast' layer7 # usermod -g gateway -G 'gateway,pkcs11,nfast' gateway
  • Three nShield Administrator cards must be available.
  • The nShield Connect appliance is running.
Program an nCipher Security World
The nCipher Security World architecture supports a specialized key management framework that spans the entire nShield family of HSMs. You must manually program a security world for the nShield Connect. The Gateway menus cannot be used to create a security world or program into an existing security world on the nShield Connect.
Prepare the Database
To prepare the database for the Security World:
  1. Clear the database of any existing Security World and keystore data:
    # /opt/SecureSpan/Appliance/libexec/ssgconfig_launch -keystoreProperty clear 4 worldb64 # /opt/SecureSpan/Appliance/libexec/ssgconfig_launch -keystoreProperty clear 4 databytes
  2. Delete any existing files from the following directory:
    # rm -f /opt/nfast/kmdata/local/*
Create the Security World
To perform the following operations, navigate using the front panel of the nShield Connect appliance. Navigate the menu using the back and confirm buttons on either side of the screen. Take note of the wheel with a select button at the center.
To create a security world:
  1. Select
    Security World mgmt
    .
  2. Select
    Module initialization
    .
  3. Select
    Create Security World
    .
Other options from the same menu include
Load Security World
and
Erase Security World
.
See Troubleshooting if you are creating a Security World and the following error appears: "key-exchange group DHPrime3072Ex not supported".     
Next, choose whether to set up the
Layer7 API Gateway
as a RFS (Remote File System) server or as a client.
Configure the Gateway
The Gateway can be configured as an RFS Server or as a Client:
3
3
Configure the Gateway as an RFS server
The following instructions configure the Gateway as a Remote File System Server.
Each nShield Connect must have a remote file system (RFS) configured. The RFS contains master copies of all the files that the nShield Connect needs:
  • the module configuration
  • feature-enabling certificates
  • the encrypted Security World and key data for Security Worlds created on the module
To use the current Gateway as the RFS server: 
  1. On the Gateway to be used as the RFS machine, retrieve the ESN and keyhash of the nShield Connect:
    # /opt/nfast/bin/anonkneti <nShield_Connect_IP>
  2. Copy the result to the clipboard. The result is in the format: "<ESN> <KNETI HASH>"
    Where:
    • <ESN>
      is the Electronic Serial Number
    • <KNETI HASH>
      is the nShield Integrity Key Hash
    For example:
    1234-010A-1AB2 001234sbcae34ab2fua3m258a02c3bd16203fe9f
  3. Create the directory structure on the RFS machine. Paste the copied result as part of the arguments; for example:
    # /opt/nfast/bin/rfs-setup --force
    <nShield_Connect_IP>
    <ESN> <KNETI HASH>
    For example:
    # /opt/nfast/bin/rfs-setup --force 10.123.123.123 1234-010A-1AB2 001234sbcae34ab2fua3m258a02c3bd16203fe9f
    The read-only and writable remote_file_system entries are added, the new config file is saved and the hardserver is configured.
  4. Edit the Gateway IP firewall to allow incoming RFS connections:
    1. Open the file
      /etc/sysconfig/iptables
      in a text editor.
    2. Add a rule above the line “ADD CUSTOM ALLOW RULES HERE”.
      For example, to allow inbound RFS connections on the default port of 9004 on the appliance's private-side network interface, add a rule similar to the following:
      # Allow inbound nShield Connect RFS connections on private interface [0:0] -A INPUT -i ssg_eth0 -p tcp -m tcp --dport 9004 -j ACCEPT # # ADD CUSTOM ALLOW RULES HERE #
    3. Save and close the
      iptables
      file.
    4. Restart the iptables service:
      # service iptables restart &
    An alternative to modifying the firewall is to disable the Gateway firewall temporarily:
        # service ssg stop
        # service iptables stop
    The firewall re-enables automatically the next time the Gateway appliance is restarted.
    Consult with your system administrator before disabling the Gateway firewall.
  5. Configure the nShield Connect appliance to use the RFS server that was just set up:
    1. On the nShield Connect display screen, use the navigation button to select the following options:
      • System
      • System Configuration
      • Remote File System
    2. Enter the IP address of the RFS machine. Leave the port number as 9004.
  6. Allow Auto Push, which permits the nShield Connect configuration to be performed remotely from the RFS:
    1. On the nShield Connect display screen, use the navigation button to select the following options:
      • System
      • System Configuration
      • Config File options
      • Allow auto push
  7. Set the IP address for the Auto-Push to the address of the RFS machine.
  8. Configure the log file storage.
    1. On the nShield Connect display screen, use the navigation button to select the following options:
      • System
      • System Configuration
      • Log Config
    2. Select a storage option:
      • Append
        --Stores the files on the nShield Connect and RFS server.
      • Log
        --Stores the files on the nShield Connect only.
  9. On the RFS machine, verify that the /opt/nfast/kmdata/local directory contains the world, module, and key files.
  10. Change the ownership and permissions of the files so that the Gateway can access them:
    # chmod 644 world # chmod 644 module_* # chmod 644 key_jcecsp* # chown gateway.nfast key_jcecsp* # chown nfast:nfast world # chown nfast:nfast module_*
Configure the Gateway as a Client
There are two scenarios for configuring the Gateway as a client:
  • The Gateway acts solely as a client, in which case you rely on another Gateway to be the RFS server. Additional configuration is required to set up synchronization with the RFS server.
  • The Gateway acts as a client and also as the RFS server.
These instructions apply to both scenarios. Additional instructions are provided to synchronize the Gateway with the RFS server.
To configure the Gateway as a client:
  1. On the nShield Connect front panel use the navigation button to select:
    • System
    • System configuration
    • Client config
    • New client
  2. Enter the IP address of the remote client.
  3. Optional. If you want a privileged connection to the client, select client privileged on any port.
  4. On the Gateway client machine, retrieve the ESN and keyhash of the nShield Connect:
    # /opt/nfast/bin/anonkneti <nShield_Connect_IP>
  5. On the client machine, configure the use of nShield Connect:
    # /opt/nfast/bin/nethsmenroll -p --force <nShield_Connect_IP>
    Confirm that the ESN and keyhash of the remote module are correct.
  6. Configure TCP sockets on the Gateway client for Java applications (for example, KeySafe):
    # /opt/nfast/bin/config-serverstartup --enable-tcp --enable-privileged-tcp
  7. Change the ownership and permission of
    /opt/nfast/kmdata/config/config
    :
    chmod 664 /opt/nfast/kmdata/config/config chown nfast:nfast /opt/nfast/kmdata/config/config
  8. Restart the hardserver:
    # /opt/nfast/sbin/init.d-ncipher restart
  9. Verify that the nfast client on the Gateway is configured correctly to use a security world with nShield Connect:
    # service ssg restart
    # /opt/nfast/bin/enquiry
    # /opt/nfast/bin/nfkminfo
    For the
    enquiry
    command, look for these lines:
    Module #1:
    [...]
    mode operational
    For the
    nfkminfo
    command, look for these lines:
    World
    [...]
    state [...] Usable [...]
    [...] Module #1
    State [...] Usable
Synchronize the Gateway as a Client with the RFS Server
Follow these additional instructions if you are configuring the Gateway solely as a client. The Gateway does not also act as an RFS Server. 
To synchronize the Gateway as a client with the RFS server:
  1. On the RFS machine, allow access from cooperating clients:
    # /opt/nfast/bin/rfs-setup --gang-client --write-noauth
    <client_IP>
  2. On the client machine, set up synchronization with the RFS machine:
    # /opt/nfast/bin/rfs-sync --setup --no-authenticate
    <RFS_IP>
  3. Update the RFS files to the client machine:
    # /opt/nfast/bin/rfs-sync --update
  4. Verify that the
    /opt/nfast/kmdata/config/config
    owner and permission settings are the same as set in the initial Configure Gateway as a Client section. Be aware that running the rfs-sync --setup command may change the permission and ownership.
    [[email protected] config]# pwd /opt/nfast/kmdata/config/config [[email protected] config]# ll total 24 -rw-rw-r-- 1 nfast nfast 514 Nov 12 04:04 cardlist -rw-rw-r-- 1 nfast nfast 18510 Nov 13 14:41 config // chmod 664, and chown nfast:nfast
  5. Set up permissions and owner for /opt/nfast/kmdata/localworld and module_* files:
    chmod 644 world chmod 644 module_filename chown nfast:nfast world chown nfast:nfast module_filename
  6. Change the file ownership and permissions so that the API Gateway can access the files:
    # chown gateway.nfast key_jcecsp* # chmod 644 key_jcecsp*
Enable the nShield Connect on the Gateway
Before enabling the nShield Connect on the Gateway, ensure that
/opt/nfast/kmdata/local
contains security world information.
The procedure for enabling the nShield Connect on the Gateway is the same as nShield Solo.
See "Enable the nShield Solo on the Gateway" under Configure the nShield Solo+.
Manage the nShield Connect Status on Gateway
The procedure to manage the nShield Connect status is the same as "Manage the nShield Solo Status on Gateway" under Configure the nShield Solo+.
Troubleshooting
5
5
Key-Exchange Group not Supported Error
When creating a Security World, the new-world utility reports the error:
# new-world -m 1 -i -Q 1/1 p new-world: module 1 not suitable: key-exchange group DHPrime3072Ex not supported new-world: Aborting world operation.
To resolve, do
one
of the following tasks:
  • Upgrade the HSM firmware to 12.50.2 NON-Fips version
  • Downgrade the client machine to a Security World older than 12.50.
  • Load an existing Security World.
Unable to Enter IP Address of the Remote Client
If this step fails with Access denied connecting to the RFS server, you need to re-run this command on the RFS server:
# /opt/nfast/bin/rfs-setup --force <nShield_Connect_IP><ESN> <KNETI HASH>
Startup Problems
After the configuration if you experience a problem starting the Gateway, it may be a file permission problem with the
/kmdata/config/config
file.To verify if you have a file permission problem with the config file, run the following command:
/opt/nfast/sbin/init.d-ncipher restart
The 'raserv' fails to start if it cannot read the
/config
file. To correct the issue, re-run the
chmod
command on the
/kmdata/config/config
file.
More information can be found under "Basic software setup" in the
nShield Connect Quick Start Guide.
  • If the nShield Connect is not yet initialized, see "Basic configuration of the nShield Connect"
  • To configure the nfast client software to use the nShield Connect, see "Configuring cooperation".