Upgrading the nShield Client for the Software Gateway

This topic discusses the procedures required to upgrade the nShield client for a nShield Connect XC HSM and API Gateway solution (in the software form factor) configuration.
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
to upgrade to Gateway version 10.0 CR 3 per this Known Issue.
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.
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
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+.
Before You Begin
Prior to performing the upgrade, the following files need to be requested and downloaded directly from Entrust support:
  • Primary client installation file: SecWorld_Lin64-12.60.11-TAC-765.iso.zip
  • Hotifx file: hotfix-TAC799.zip
Step 1 - Stop Running Gateway and Disable nShield HSM
Before performing your upgrade, you'll need to stop any running Gateways first and then disable the nShield Connect HSM.
To stop the Gateway
/opt/SecureSpan/Gateway/runtime/bin/gateway.sh stop
To disable the nShield HSM
  1. View the software Gateway HSM configuration menu, by running 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 1 on your keyboard. 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
  4. Press 2 on your keyboard to disable Gateway use of the configured nShield HSM.
  5. 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 2 - Perform Backup of Local nShield HSM Data
Back up all local nShield HSM data from the following directory in your Gateway:
Step 3 - 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 a Software Gateway. Skip this part if you've already upgraded to version 10.0 CR 3 of the API Gateway.
Step 4 - 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 nShield hardserver, run the following command:
# /opt/nfast/sbin/init.d-ncipher stop
To stop the Gateway from running, run the following command:
# /opt/SecureSpan/Gateway/runtime/bin/gateway stop
Step 5 - Uninstall Existing nShield Client
Perform the removal of the existing nShield Client per latest Entrust documentation.
Step 6 - Install New nShield Client and Client Libraries
The required SecWorld_Lin64-12.60.11-TAC-765.iso.zip file can be retrieved directly from Entrust support.
Ensure that nShield client software (version 12.60.11) has been installed on the machine hosting the Gateway, per the instructions outlined in the nShield user documentation.
For other tips and prerequisites for the client installation that address your software Gateway configuration, refer to theSecurity World Client Software section of the Configure nShield Connect for the Software Gateway techdocs page.
Step 7 - Install nShield Hotfix
The required hotfix-TAC799.zip file can be retrieved directly from Entrust support.
Unzip the hotfix-TAC799.zip file and locate and follow the instructions contained in the release.txt file that describe the steps to apply the hot fix. Included should be instructions for the replacement nCipherKM.jar file.
Step 8 - 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
directory of your Gateway. This includes all required world, module, keystore, and key files.
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. Assuming your software Gateway is set up as a client only, run the following commands to ensure the Gateway continues to have access to the files found in the
# chown gateway.nfast key_jcecsp* # chmod 644 key_jcecsp*
Step 9 - Configure Gateway System Properties
  1. Go to the following directory to locate the system.properties file:
  2. Insert the following line to the system.properties file:
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 nShield hardserver with this command:
    # /opt/nfast/sbin/init.d-ncipher start
  2. Load the software Gateway HSM configuration menu again with the following command:
  3. From the configuration menu, press the 1 key (Manage HSM) and then the 1 key again (Manage Gateway nShield HSM status) from the nShield HSM  configuration menu. 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
  4. Press 1 key to choose the 'Enable Gateway use of the nShield HSM' option.
  5. 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.