Upgrading nShield Client for the Gateway Appliance

This topic discusses the procedures required to upgrade the nShield client for a nShield HSM and API Gateway Appliance solution configuration.
The general steps for upgrading the nShield client apply to both nShield Solo and Connect users unless otherwise specified. Where appropriate, cross references are made to other Techdoc pages that describe related nShield HSM configuration information.
Gateway version 10.0 CR 3+ Users
nShield HSM users who plan to upgrade to Gateway version 10.0 CR 3 or higher MUST upgrade their nShield client to version 12.60.11.
nShield HSM users that require their nShield HSM to run in FIPS mode are advised
NOT
to upgrade to Gateway version 10.0 CR 3 per this Known Issue.
Learn which nShield HSM devices are compatible with your API Gateway version here.
Upgrade Procedures:

Upgrade to nShield Client Version 12.60.11

The following steps apply to Gateway version 10.0 CR 3+ installations with an nShield HSM as a keystore. You
MUST
install version 12.60.11 of the nShield client in order for your nShield HSM to work with API Gateway version 10.0 CR 3+.
Contents:
3
3
Before You Begin
An RPM file is required to perform this upgrade. The following nShield client RPM file can be retrieved from the API Gateway Solutions and Patches page:
  • ssg-nshieldpci-12.60.11-2.el7.x86_64.rpm
Step 1 - Stop Running Gateway and Disable nShield HSM
Before performing your upgrade, you'll need to stop any running Gateways and disable the nShield Connect HSM.
Step 2 - Disable Gateway Use of the nShield HSM
  1. From the API Gateway Menu, select option 6 to view the Manage Gateway nShield Status menu.
  2. Select option 1 (Manage Gateway nShield Status) to disable the nShield HSM.
  3. Stop or restart the Gateway so that the Gateway will default back to 'Software DB' as the keystore. You may verify this in Manage Private Keys of the Policy Manager.
Step 3 - Perform Backup of Local nShield HSM Data
Back up all local nShield HSM data from the following directory in your Gateway:
/opt/nfast/kmdata/local
Step 4 - Perform the API Gateway 10.0 CR 3 Upgrade
After you've disabled your nShield HSM keystore and backed up your HSM data, perform the patching process to upgrade your API Gateway to version 10.0 CR3 as outlined in Patch an Appliance Gateway . Skip this part if you've already upgraded to version 10.0 CR 3 of the API Gateway.
Step 5 - Stop the Gateway and nShield Hardserver
Prior to uninstalling an existing nShield client, you'll need to stop the Gateway and the nShield hardserver. The hardserver controls communication between applications such as the API Gateway and an nShield HSM.
To stop the Gateway from running, run the following command:
# service ssg stop
To stop the nShield hardserver, run the following command:
# /opt/nfast/sbin/init.d-ncipher stop
Step 6 - Uninstall Existing nShield Client RPM
Run the following command to uninstall the existing nShield client RPM:
rpm -e <ssg package name>
Step 7 - Install New nShield Client RPM
To install a new nShield client RPM:
  1. Run the following command:
    rpm -ivh <ssg rpm file>
  2. Verify the installation of the new nShield client:
    /opt/nfast/bin/enquiry
    This nShield command displays all the installed nShield modules that are operational.
  3. Applicable to nShield Connect users only
    • After verification of a successful installation, proceed to configure the Gateway as a client. The configuration steps differ depending on whether you plan your Gateway to act solely as a client or as both a client and RFS server. For a refresher on how this is configured, see nShield Connect instructions for client configuration.
Step 8 - Configure Gateway System Properties
  1. Go to the following directory to locate the system.properties file:
    /opt/SecureSpan/Gateway/node/default/etc/conf/
  2. Insert the following line to the system.properties file:
    com.l7tech.ncipher.preference=highest
Step 9 - Post-Client Install - Check File Permission and Ownership Settings
After installing the new nShield client, ensure that all the required nShield HSM data is present in the
/opt/nfast/kmdata/local
directory of your Gateway. This includes all required world, module, keystore, and key files. The required files may vary depending on your nShield HSM device and model.
Next, ensure that the file ownership and permissions have not changed since the initial HSM configuration so that the Gateway can continue to access those files.
nShield Solo+ HSM
Ensure the following file ownership and permission settings have not changed after the client upgrade by running the following sample commands:
# chown gateway.nfast key_jcecsp* # chown gateway.nfast module* # chown gateway:nfast world # chmod 664 key_jcecsp* # chmod 664 module* # chmod 664 world
nShield Connect HSM
This procedure applies to both Connect+ and Connect XC HSM models. Ensure file ownership and permission settings have not changed after the client upgrade.
For example, if you have configured the Gateway solely as a client, run the following sample commands:
# chown gateway.nfast key_jcecsp* # chmod 644 key_jcecsp*
Step 10 - Restart the Gateway and Re-enable the nShield HSM
After checking that the Gateway still has the required permission and ownership settings to access nShield files, you may restart the Gateway and re-enable the nShield HSM:
  1. Restart the Gateway machine.
  2. From the API Gateway Main Menu, select option 6 to view the Manage Gateway nShield Status Menu.
  3. Select option 1 (Manage Gateway nShield Status) to enable the nShield HSM.
  4. You may verify that the nShield HSM is now being used by the Gateway as the keystore in Manage Private Keys of the Policy Manager.