Configure the nShield Solo+

The gateway appliance can use the nShield Solo+ from Thales e-Security as the hardware security module (HSM). This topic describes how to set up the Security Worlds for this HSM, using either the Gateway menus or by programming the security world manually. After the HSM is configured, you can switch between using it or the internal Gateway database as the keystore.

gateway91

The CA API Gateway appliance can use the nShield Solo+ from Thales e-Security as the hardware security module (HSM). This topic describes how to set up the Security Worlds for this HSM, using either the Gateway menus or by programming the security world manually. After the HSM is configured, you can switch between using it or the internal Gateway database as the keystore.

A Security World contains some or all the following:

One or more Thales nShield Solo+ cards

An Administrator Card set (ACS). These cards control access to the Security World configuration. They are also used in recovery and replacement operations. Tip:
When creating a Security World using the Gateway menus, only the Administrator Card set is created.

(Optional) One or more Operator Card sets (OCS). These cards control access to application keys.

Some cryptographic key and certificate data that is encrypted using the Security World key and stored on the host computer(s).

You can add or remove cards, keys, and even hardware security modules at any time. These components are linked by the Security World key, which is unique to each world.

Both of these refer to the Thales Solo+ HSM. The name "nShield" is the current name of the product, but "nCipher" may still be referenced on the Gateway.

Contents:

Preconditions

The ssg-nshieldpci
RPM is installed. You can verify this RPM with this command, which returns the version of the installed RPM:

# rpm -qa | grep ssg-nshieldpci

The layer7
and gateway
users are in the nfast group. You can verify this by running this command:

# egrep -i "^nfast" /etc/group

The response should be:

nfast:x:502:gateway,layer7

If you do not see the expected response, add the users with these commands:

# usermod -g layer7 -G 'layer7,nfast' layer7
# usermod -g gateway -G 'gateway,pkcs11,nfast' gateway

Three nShield Administrator cards are available.

The card reader is connected to the back of the Gateway appliance. The port is on the upper right side, near the blue light.

The nShield Solo+ HSM is operating correctly (see "Verify Correct Operation of HSM" below),

Verify Correct Operation of HSM

You can verify that your nShield Solo+ HSM is running correctly with these steps:

Open a privileged shell.

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

Verify the module with this command:

# /opt/nfast/bin/enquiry

You should see a "Module 1
" section listed.

If the module is not running, execute following command:

# /opt/nfast/sbin/install

Verify that the nfp kernel is loaded:

# lsmod | grep nfp

You should see: 'nfp 24639 2'
or similar returned.

Close the privileged shell to return to the Gateway main menu.

Create a New Security World Using the Gateway

The CA API Gateway menus provide a straightforward way to create a security world in the nCipher module. All options are fixed (for example, three nShield cards are always used).

If you need to customize your security world, create it manually instead. Follow the procedure described under "Setup A: Manually Create a Security World".

To create a security world:

Access the Gateway main menu and then select options 6
(Manage HSM), then 2
(Create new security world).

Follow the instructions on the screen.

Ensure that you have access to three Administrator Control Set (ACS) cards. These cards control access to recovery and replacement functionality. Tip:
Operator Control Set (OCS) cards are not used when configuring using the Gateway menus.

Ensure that the module switch on the back of the HSM is in the "I" position. The three switch positions are:

I
(Initialize)

O
(Operational)

M
(Maintenance)

Insert the first card in to the reader when prompted.

Enter the passphrase for the card and reenter to confirm.

Remove the card and repeat for the second and third cards.

Optional: Disconnect the card reader. Switch the toggle switch to the "O" position (center position).

You should now see menu options to enable or disable the HSM. Choose 1
(Enable Gateway use of the nCipher HSM). Enter y
to start the Gateway when prompted.

Start the Policy Manager and then run the Manage Private Keys task.

Keystore location is now "nCipher HSM"

One private key corresponding to the cluster hostname is created and set as the default SSL

Program Into an Existing Security World Created Using the Gateway

Follow this section to program into an existing security world that was created previously using the Gateway.

If the existing security world was created originally using the manual procedure (see "Setup A: Manually Create a Security World "), use "Setup B: Manually Program into an Existing Security World" instead.

Precondition:
The database contains a security world.

To program into an existing Security World:

Access the Gateway main menu and select option 6
(Manage HSM).

Select option 3
(Program into existing security world)

Follow the instructions on the screen.

Have the first two cards from "Create a New Security World" on hand.

Ensure that the card reader is connected.

Ensure the module switch on the back of the HSM is in the "I" position.

Insert card #1 and enter the passphrase. This passphrase is from step 4 under "Create a New Security World".

Remove card #1 and then insert card #2.

Enter the passphrase and then remove card #2.

(Optional) Disconnect the card reader.

Move the module switch to the "O" position. At this point, a menu to enable or disable the HSM is displayed. Chose option 1
(Enable Gateway use of the nCipher HSM). Enter y
to start the Gateway when prompted.

Connect to the Gateway using the Policy Manager.

Run Manage Private Keys.

The keystore location now shows "nCipher HSM"

You see the same keys as in the node where the security world was created

Manually Programmed Security Worlds

This section describes how to create and program security worlds directly into the nCipher module, without using the Gateway menus. For advanced users, this method offers the greatest flexibility and customization.

If you are new to Thales HSMs, consider using the steps under "Create a New Security World Using the Gateway" and "Program Into an Existing Security World Created Using the Gateway" instead.

Prerequisites:

Clear the database of any existing security world and keystore data with these commands:

# /opt/SecureSpan/Appliance/libexec/ssgconfig_launch -keystoreProperty clear 4 worldb64# /opt/SecureSpan/Appliance/libexec/ssgconfig_launch -keystoreProperty clear 4 databytes

Delete any existing files from the following directory:

# rm -f /opt/nfast/kmdata/local/*

Before deleting an existing world from the module, perform all administrative operations that require the security world. For example, erase any operator cards that were created manually. Security worlds created using the nCipher HSM menu only use administrator cards, not operator cards. If reusing the existing security world, ensure that its administrator cards are stored in a safe place and that the previous contents of kmdata/local are backed up.

Next, perform either Setup A or Setup B below.

Setup A: Manually Create a Security World

Perform this setup to create a new security world manually in the nCipher module.

Put the HSM module into pre-initialization mode:

Set the physical switch on the module to the "I" position (left-most position).

Change mode by running the reset command:

# /opt/nfast/bin/nopclearfail ca

Verify the module is in pre-initialization mode by running the command:

# /opt/nfast/bin/enquiry -m 1 | grep mode

You should see the message: "mode pre-initialization"

Create the security world using the new-world
command. The following example command does the following:

Creates a world on the first module that is FIPS Level 2 compliant

Create three administrator cards, any two of which must be inserted to authorize certain administrative actions

The following command must be run as the nfast
user. If you are not logged in as the nfast
user, switch to this user by running the "su - nfast
" command first.

# /opt/nfast/bin/new-world -m 1 -s 0 [-i] -Q 2/3 [-F] -k rijndael

Where:

-m
sets the module in which the security world is created ("1" refers to the nShield card)

-s
sets the slot ("0" refers to slot 0 of the module)

(Optional) -i
initializes a new security world and programs it into a module. (This switch is required if there is an existing world, as the default behavior uses that world instead of creating a new one.)

-Q
sets the quorum of cards ("2/3" indicates that three cards are created but only two are needed for administrative operations)

(Optional) -F
enables full FIPS 140-2 level 3 compliance

-k
sets the key type for the module keys ("rijndael" refers to the Rijndael algorithm)

Follow the on-screen instructions, inserting administrator cards and entering passphrases as prompted. If the Security World is created successfully, you see this message:

'security world generated on module #1'

Put the HSM module into Operational mode:

Move the physical switch on the back of the HSM module to the "O" position (middle position).

Change the mode of the HSM module by running the reset command:

# /opt/nfast/bin/nopclearfail ca

Check that the security world was set up properly with this command:

# /opt/nfast/bin/nfkminfo

In the output, look for a World section with text similar to this:

"Initialised Usable Recovery !PINRecovery !ExistingClient RTC NVRAM FTO SEEDebug StrictFIPS140"

You can now enable the HSM on the CA API Gateway. For details, see "Enable the nShield Solo on the Gateway" later in this topic.

Setup B: Adding a HSM to an Existing Security World

Perform this setup if you want to add a HSM to an existing Security World. Examples of when you may want to do this:

The HSM was previously removed from the same Security World and you wish to add it back.

You wish to continue using existing keys and Operator cards after replacing a HSM or upgrading the firmware on a HSM.

Prerequisites

Ensure that you have:

A copy of the Security World data on the host machine (in the /opt/nfast/kmdata/local directory)

Sufficient Administrator cards (same number as used to create the original Security World)

The passphrases for the Administrator cards

To manually program into an existing Security World:

If the Security World data does not already exist on this host, copy the following files to the /opt/nfast/kmdata/local
directory of the Gateway. You can obtain these files from the /opt/nfast/kmdata/local
directory of another Gateway, or from another client machine that uses the NetHSM's security world.

The world
file from an existing Security World

The module
file from the existing Security World

(Optional) These existing keystore and key files:

A single
key_jcecsp_YYYY
file (where 'YYYY' is the keystore ID). This file is created with the existing security world either by the CA API Gateway or by a Java program using the KeyStore.nCipher.sworld
keyStore type

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.

Change the owner and group of the copied files and the module file:

# chown gateway.nfast key_jcecsp*# chown gateway.nfast module*# chmod 664 module*

Set the nShield module into pre-initialization mode:

Set the physical switch on the back of the HSM module to the "I" position.

Switch the mode of the HSM by running the command:

# /opt/nfast/bin/nopclearfail ca

Verify the mode by running the command:

# /opt/nfast/bin/enquiry -m 1 | grep mode

You should see the message: "mode pre-initialization"

Program the module into the existing security world with this command:

# /opt/nfast/bin/new-world --program --module=1

Follow the on-screen instructions, inserting administrator cards and entering passphrases as prompted. When the programming is complete, you should see a message beginning with: "security world loaded on..."
. Example:

# /opt/nfast/bin/new-world --program --module=114:35:44 WARNING: Module #1: preemptively erasing module to see its slots!Indoctrinating Module: Module 1: 0 cards of 2 read Module 1 slot 0: Admin Card #3 Module 1 slot 0:- passphrase supplied - reading card Module 1: 1 card of 2 read Module 1 slot 0: Admin Card #3: already read Module 1 slot 0: empty Module 1 slot 0: Admin Card #1 Module 1 slot 0:- passphrase supplied - reading cardCard reading complete.security world loaded on 1 module; hknso = 3f58091778215ec3919076619142f5348ee295d3

Set the nShield module to the Operational mode:

Set the physical switch on the HSM to the "O" position (middle position).

Switch the mode of the HSM by running the command:

# /opt/nfast/bin/nopclearfail ca

Verify the mode by running the command:

#/opt/nfast/bin/enquiry -m 1 | grep mode

You should see the message: "mode operational"

Check that the security world was set up properly with this command:

# /opt/nfast/bin/nfkminfo

In the output, look for a World section with text similar to this:

"Initialised Usable Recovery !PINRecovery !ExistingClient RTC NVRAM FTO SEEDebug StrictFIPS140"

Enable the nShield Solo on the Gateway

Once setup A or B has been performed, you can enable the nShield Solo on the CA API Gateway.

Start the Gateway service, if it has been stopped:

# service ssg start

Access the Gateway main menu and select option 6
(Manage HSM).

Select option 4
(Use manually-programmed security world).

Follow the on-screen instructions.

If the database does not contain any security world information, the contents of
kmdata/local
is copied to the database

If the database contains security world information that is different from kmdata/local
, specify whether to replace the one in the database

If the database and kmdata/local
both contain the same security world information, nothing happens

Select option 1
(Enable Gateway use of the nCipher HSM). Enter y
to start the Gateway when prompted.

Start the Policy Manager and connect to the Gateway.

Run Manage Private Keys.

The keystore location now shows "nCipher HSM".

Any existing keys are viewable.

Manage the nShield Solo+ Status on the Gateway

You can set the CA API Gateway to use either the Thales HSM or the internal database as the keystore.

For more information about the Thales HSM menu options, see Manage Gateway Thales nShield HSM Status Menu.

Prerequisite:
If using the Thales HSM, ensure that the module switch on the HSM is set to the "O" position.

Access the Gateway main menu and select option 6
(Manage HSM).

Select option 1
(Manage Gateway nCipher HSM status).

To use the Thales HSM, select 1
(Enable Gateway use of the nCipher HSM).

To use the internal database, select option 2
(Disable Gateway use of the nCipher HSM).

To verify that the change took effect:

Return to the Gateway main menu and choose option 2
(Display CA API Gateway configuration menu).

Select option
7
(Manage CA API Gateway status), then option 1
(Start the CA API Gateway)

In the Policy Manager, run Manage Private Keys. The keystore location shows "nCipher HSM" if the HSM is enabled; otherwise it shows "Software DB" if the HSM is disabled.

View Information About the nShield Solo+ HSM

Use the following commands to view information about your Thales nShield Solo+ HSM. These will help during troubleshooting. Tip:
Run the commands from a privileged shell.

To view the...	Run this command...	What to look for...
HSM firmware revision	# /opt/nfast/bin/enquiry	Look under ‘Module #1:’ section for the “version” line.
nfast service version	# /opt/nfast/bin/enquiry	Look under ‘Server:’ section for the “version” line.
Card model	# /opt/nfast/bin/enquiry	Look under: ‘Module #1:’ section for the “speed index” line.
Driver version	# /opt/nfast/bin/ncversions	Look for the “nfdrv” line

Location of the log file for the Thales nShield HSM:

/opt/nfast/log/hardserver.log

Configure Thales Hardware Security Modules

Content feedback and comments

CA API Gateway 9.1

Configure the nShield Solo+