CA API Gateway 9.1

9.4 9.1

Configure the Thales nCipher HSM

If a Thales nCipher HSM (Hardware Security Module) is installed on the appliance, use option 6 from the Gateway main menu to configure it.
gateway83
If a Thales nCipher HSM (Hardware Security Module) is installed on the
API Gateway
 appliance, use option
6
 from the Gateway main menu to configure it.
Prerequisite
Ensure you’ve run the Thales nCipher install script to ensure correct operation of your HSM:
  2. Check the run levels for the
    nc_hardserver
     and
    nc_drivers
     daemons with these commands:
    # chkconfig --list | grep nc_hardserver
# chkconfig --list | grep nc_drivers
    The daemons must be "on" for levels 2, 3, 4, 5. If not, turn them on using these commands:
    # chkconfig --level 2345 nc_hardserver on
# chkconfig --level 2345 nc_drivers on
  3. Check the module with this command:
    # /opt/nfast/bin/enquiry
    You should see a "Module 1" section listed.
  4. If the module is not running, execute following command:
    # /opt/nfast/sbin/install
  5. Close the privileged shell and return to the Gateway main menu.
    The
    API Gateway
     does not currently support AES-GCM when using a Thales nCipher Hardware Security Module with a custom FIPS level 3 security world.
    This menu allows you to configure the nCipher Hardware Security Module on the CA API Gateway Appliance

What would you like to do?

1) Manage Gateway nCipher HSM status
2) Create new security world
3) Program into existing security world
4) Use manually-programmed security world
X) Exit menu

Please make a selection:
Option
Description
1) Manage Gateway nCipher HSM status
Select this option to enable or disable
API Gateway
 use of nCipher.
  • Enter
    1
     to enable
    API Gateway
     use of the nCipher HSM.
    Enabling nCipher on a
    API Gateway
     will generate a new random master passphrase, using the nCipher module’s hardware random number generator.
    The database password and the cluster passphrase are automatically re-encrypted with the new master passphrase.
  • Enter
    2
     to disable
    API Gateway
    y use of the nCipher HSM.
    Disabling nCipher on a
    API Gateway
     will reset the master passphrase back to the default
    7layer
    . You can change the passphrase.
    When nCipher is disabled, the
    API Gateway
     will revert to using the software DB as its default keystore. If a SafeNet Luna HSM has been configured, it is used instead. For more information about keystores, see Manage Keystores.
2) Create new security world
Select this option to initialize the nCipher card and create a new security world cardset. You will choose this option if there is no existing security world in which to program the card.
  1. Ensure that the card read is connected to the nCipher HSM and that the module switch on the HSM is in the "I" position (pre-initialization mode). The initialization will require at least three blank cards.
  2. Press [
    Enter
    ] to proceed.
  3. Insert the blank cards when prompted and be sure to make note of the passphrase used to protect each card. These will be needed to program additional modules (or to reprogram this one) into the security world.
  4. When the initialization is complete, set the module switch to the "O" position (operational mode).
  5. Disconnect the card reader and then enable the HSM as prompted using option
    1
     (Manage Gateway nCipher HSM Status).
  6. Exit to the Gateway main menu.
    Select option
    2
     (Display Gateway configuration menu) to display the Configure Gateway menu.
    Select option
    7
     (Manage Gateway status) to restart the
    API Gateway
    .
If you lose access to the security world, you must re-enter the database password and cluster passphrase.
3) Program into existing security world
To use this option, the
API Gateway
 node should be configured to use a database that already contains a security world.
Select this option to program the nCipher card into an existing security world. You will need at least two cards from the security world’s cardset along with the passphrases.
  1. Ensure that the card reader is connected to the nCipher HSM and that the module switch on the HSM is in the "I" position (pre-initialization mode).
  2. Press [
    Enter
    ] to proceed.
  3. Insert the cards and enter the passphrase as prompted.
  4. When the initialization is complete, set the module switch on the HSM to the "O" position (operational mode).
  5. Disconnect the card reader and then enable the HSM as prompted using option
    1
     (Manage Gateway nCipher HSM Status).
  6. Exit to the Gateway main menu.
    Select option
    2
     (Display Gateway configuration menu) to display the Configure Gateway menu.
    Select option
    7
     (Manage Gateway status) to restart the
    API Gateway
    .
4) Use manually-programmed security world
To be able to use this option, you must either have manually created a new security world on the nCipher module or programmed the module into an existing security world. For details, see "How to Manually Set Up the nCipher Card" below.
 
 
Select this option to direct the Gateway to use a security world that has already been manually programmed.
Press [
Enter
] to proceed. The configurator checks the status of a security world in the database and takes the following actions:
  • No world information present in database:
     If the database does not contain an nCipher security world, the new world is simply copied to the database. Press [
    Enter
    ] to continue when prompted.
  • Matching world information already in database:
     If the database already contains a matching security world, no further action is required. Press [
    Enter
    ] to continue when prompted.
  • Conflict with security world in database:
     If the database already contains a different security world, you are prompted to delete it and replace it with the security world on the disk. Type "
    proceed
    " (without the quotes) to continue. Entering anything else will cancel the process.
You may be prompted to choose a keystore ID.
Choosing a Gateway Keystore
When enabling nCipher support with a manually-programmed security world (option
4
), you may be prompted to choose a keystore ID to be used by the
API Gateway
 as the "nCipher HSM" keystore. This will occur if the database does not yet contain a designated keystore ID and more than one keystore ID is present.
More than one keystore ID is present on the local node.  Please choose a keystore ID for the Gateway
to use as its "nCipher HSM" keystore:

0b77a92f68c4568d059da676279673fd2abf7562 (contains 1 object)
67422c431301bcac9f256e6ada4a23d92ff2133b (contains 0 objects)
9a9307c169fc94240b7b1b1f61319763e5fe7510 (contains 3 objects)

Enter the first few unique digits of the keystore ID to use that keystore ID with the Gateway. 
Enter "list" to see a list of available IDs.
Enter "list " followed by a keystore ID to attempt to list its contents (assumes module-protection).

Choice (list|<ID>|list <ID>):
Select one of the following:
  • Enter
    list
     to redisplay the list of available keystore IDs.
  • Enter
    list
    <ID>
     to view the contents of a particular keystore ID (see below for details)
  • Enter the
    <ID>
     of a keystore to select it. You do not need to enter the entire ID -- just the first few unique characters. Using the example IDs, simply entering the first character of the ID would be sufficient.
Using the "list <ID> command
You may be able to inspect the contents of a particular keystore by entering "list" followed by the first few unique characters of the keystore ID -- for example:
list 9a9
.
Enter the first few unique digits of the keystore ID to use that keystore ID with the Gateway. 
Enter "list" to see a list of available IDs.
Enter "list " followed by a keystore ID to attempt to list its contents (assumes module-protection).

Choice (list|<ID>|list <ID>): list 9a9

Keystore ID 9a9307c169fc94240b7b1b1f61319763e5fe7510 contains 3 entries:

ssl, 2048 bit RSA, CN=l7tech.example.com
acme, 1024 bit RSA, CN=acme
warehouse, 2048 bit RSA, CN=global
After inspecting the keystore, you can either enter its ID to select it, or use the
list
 command to redisplay the list of available keystore IDs or inspect another keystore.
How to Manually Set Up the nCipher Card
In order to use option
4
 ("Use manually programmed security world"), there must either be a manually created security world on the nCipher module or a module has been programmed into an existing security world. Follow the appropriate scenario below.
Setting Up NetHSM and nShield Connect:
For instructions on how to manually configure a NetHSM or nShield Connect, please refer to the user documentation provided by Thales. When you have completed setting up the nShield Connect and configuring the security world, the 
API Gateway
 will be ready to work with nShield Connect; you only need to use option 
4
 to instruct the 
API Gateway
 to use the manually preconfigured security world
Scenario 1: Your
API Gateway
 appliance or virtual appliance is using a network-attached nShield Connect
Use of an nShield Connect from a
API Gateway
 appliance that is already equipped with an internal HSM is not supported.
Please refer to the
nShield Connect Quick Start Guide
 provided by Thales for information on setting up the
API Gateway
 to use nShield Connect. Note the following however:
  • Clear any existing data in
    kmdata/local
     using these commands:
    1. Log in as
      ssgconfig
       and open a privileged shell.
    2. At the command prompt, enter:
      # cd /opt/nfast/kmdata/local
      # rm - f *
  • You do not need to install the nfast client software, as it will already be present on appliances that were shipped with nCipher cards.
  • If you are using the
    API Gateway
     as an RFS server, you must configure the
    API Gateway
     IP-level firewall to permit access. 
  • If you are using the
    API Gateway
     as a client only (relying on another
    API Gateway
     to be the RFS server), do the following:
    1. Perform the steps under
      "Setting up client cooperation"
       in the
      nShield Connect User Guide
      . This sets up the client to synchronize with the RFS server.
    2. Log in as
      ssgconfig
       and open a privileged shell.
    3. Run the following command to update the RFS files to local storage:
      # /opt/nfast/bin/rfs-sync  - -update
    4. Run the following command to set the permissions for the updated files:
      # chown gateway.nfast key_jcecsp*
      These steps populate 
      kmdata/local
       with the 
      kmdata/local
       files from the RFS server.
Other notes to consider:
  • If the nShield Connect is not yet initialized, see "Basic configuration of the nShield Connect" under "Basic software setup" in the
    nShield Connect Quick Start Guide
    .
  • To configure the nfast client software to use the nShield Connect, see "Configuring cooperation" under "Basic software setup" in the
    nShield Connect Quick Start Guide
    .
You can verify that the nfast client software on the
API Gateway
 appliance is correctly configured to use a security world with nShield connect by running the following commands after restarting the
API Gateway
 appliance:
# /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
Once verified, you can configure the
API Gateway
 to use the HSM by running option
4
.
Using the
API Gateway
 as an RFS Server
To use the
API Gateway
 appliance as an RFS (Remote File System) server, you will need to allow access through the
API Gateway
 IP firewall. You can do this by either by temporarily turning off the firewall or by adding a rule to allow incoming RFS connections.
To turn off the
API Gateway
 IP firewall
:
  1. Log in as
    ssgconfig
     and open a privileged shell.
  2. At the command prompt, enter:
# service ssg stop
# service iptables stop
This turns off the firewall. The firewall will be automatically re-enabled the next time the
API Gateway
 appliance is restarted.
Confirm with your system administrator that it is safe to disable the
API Gateway
 IP firewall.
To edit the firewall to permit incoming RFS connections
:
  1. Locate and open the following file in a text editor:
    /etc/sysconfig/iptables
  2. Add an allow rule for the desired port on the desired interface about 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 eth0 -p tcp -m tcp --dport 9004 -j ACCEPT
#
# ADD CUSTOM ALLOW RULES HERE
#
  3. Save and close the
    iptables
     file and then enter the following command to make the changes effective:
    # service iptables restart &
Scenario 2: Your
API Gateway
 appliance has an internal nShield HSM
The instructions in this section are intended only for an internal nCipher module and not a NetHSM or nShield Connect. For information about setting up one of these other products, please refer to the nCipher documentation.
To manually create a new security world on a
API Gateway
 appliance internal HSM:
You do not need to manually create a security world if you are using a
API Gateway
 appliance internal nCipher HSM unless you wish to customize the security world settings.
  1. Before deleting any existing world from the module, ensure you have performed any administrative operations that require the security world. (For example, erasing any operator cards you may have manually created. Note that worlds created via the nCipher HSM menu only use administrator cards and do not use any operator cards.) If the existing security world will be reused, ensure that its administrator cards are stored in a safe place and that the previous contents of
    kmdata/local
     are backed up.
    If necessary, clear any existing nCipher data from the
    API Gateway
     database.
  2. Log in as
    ssgconfig
     and open a privileged shell.
  3. At the command prompt, enter the following commands to delete any existing data in
    kmdata/local
    :
    # cd /opt/nfast/kmdata/local
# rm  - f *
  4. Ensure that the module switch on the back of the HSM is in the "I" position (pre-initialization mode).
    You can query the current status of the module switch by running these commands:
    # /opt/nfast/bin/nopclearfail ca
    # /opt/nfast/bin/enquiry -m 1 | grep mode
    The screen will display messages such as "mode operational" or "mode pre-initialization" depending on the position of the switch.
  5. Reset the module by entering this command:
    # /opt/nfast/bin/nopclearfail ca
  6. Create a new security world with this command:
    # /opt/nfast/bin/new-world -m 1 -s 0 -Q 2/3 -k rijndael
    This creates a world on the first module that is FIPS Level 2 compliant, creating three administrator cards, any two of which must be inserted in order to authorize certain administrative actions.
  7. Follow the instructions displayed by the new-world command, inserting administrator cards as prompted.
  8. Change the module switch on the back of the HSM to the "O" position (operational mode).
  9. Reset the module again:
    # /opt/nfast/bin/nopclearfail ca
  10. Check the security world with this command:
    # /opt/nfast/bin/nfkminfo
    The "World" section at the top should show a "state" similar to:
    Initialised Usable Recovery !PINRecovery !ExistingClient RTC NVRAM FTO SEEDebug StrictFIPS140
To manually program a
API Gateway
 appliance internal nCipher HSM into an existing security world
:
You do not need to manually program an existing security world if you are using a
API Gateway
 appliance internal nCipher HSM and are configuring a node from a cluster that already contains nCipher security world information in its database.
  1. Before deleting any existing world from the module, ensure you have performed any administrative operations that require the security world. (For example, erasing any operator cards you may have manually created. Note that worlds created via the nCipher HSM menu only use administrator cards and do not use any operator cards.) If the existing security world will be reused, ensure that its administrator cards are stored in a safe place and that the previous contents of
    kmdata/local
     are backed up.
  2. If necessary, clear any existing nCipher data from the
    API Gateway
     database.
  3. Log in as
    ssgconfig
     and open a privileged shell.
  4. At the command prompt, enter the following commands to delete any existing data in
    kmdata/local
    :
    # cd /opt/nfast/kmdata/local
# rm  - f *
  5. Copy the following files to
    /opt/nfast/kmdata/local
    .
    • Your existing security world's "world" file.
    • (Optional)
      A single "key_jcecsp_
      YYYY
      " file (where "YYYY" is the keystore ID) for your existing keystore ID created within the existing security world either by the
      API Gateway
       or by a Java program using the KeyStore.nCipher.sworld KeyStore type
    • (Optional)
       One or more "key_jcecsp_
      YYYY
      -key-
      ZZZZ
      " files (where "ZZZZ" is a hexadecimal identifier), one for each private key entry within your existing keystore ID.
    The owner and group of all the 
    key_jcecsp
     files must be 
    gateway
     and 
    nfast
    , respectively. If not, permission denied errors will occur when the 
    API Gateway
     is restarted. To set this, use the following command:
    # chown gateway.nfast key_jcecsp*
  6. Ensure that the module switch on the back of the HSM is in the "I" position (pre-initialization mode). To check the current status of the module switch.
  7. Reset the module by entering this command:
    # /opt/nfast/bin/nopclearfail ca
  8. Program the module into the existing security world with this command:
    # /opt/nfast/bin/new-world --program --module=1
  9. Follow the instructions displayed by the new-world command, inserting existing administrator cards as prompted.
  10. Change the module switch on the back of the HSM to the "O" position (operational mode).
  11. Reset the module again:
    # /opt/nfast/bin/nopclearfail ca
  12. Check the security world with this command:
    # /opt/nfast/bin/nfkminfo
    The "World" section at the top should show a "state" similar to:
    Initialised Usable Recovery !PINRecovery !ExistingClient RTC NVRAM FTO SEEDebug StrictFIPS140
How to Manually Clear the Database
If the
API Gateway
 database contains an existing keystore ID within the desired security world, it will use that keystore ID instead of one that may already be present in
kmdata/local
.
To clear all nCipher security world and keystore information from the database
:
  1. On a configured cluster node, log in as
    ssgconfig
     and open a privileged shell.
  2. At the command prompt, enter the following two commands (note each command is entered on a single line):
    # /opt/SecureSpan/Appliance/libexec/ssgconfig_launch -keystoreProperty clear 4 worldb64
# /opt/SecureSpan/Appliance/libexec/ssgconfig_launch -keystoreProperty clear 4 databytes
How to Obtain Information About the nCipher HSM
There are several commands that you can run to view the version numbers and card model of your Thales nCipher HSM.
To obtain information about the nCipher Card:
  2. Run the appropriate command:
  • To view the HSM firmware revision:
    # /opt/nfast/bin/enquiry
    Look under ‘Module #1:’ section for the “version” line.
  • To view the nfast service version:
    # /opt/nfast/bin/enquiry
    Look under ‘Server:’ section for the “version” line.
  • To view the card model:
    # /opt/nfast/bin/enquiry
    Look under: ‘Module #1:’ section for the “speed index” line/
  • To view the driver version:
    # /opt/nfast/bin/ncversions
    Look for the “nfdrv” line.

Content feedback and comments