Install and configure the Entrust nShield HSM

Install the nShield Security World Software

  1. Sign in to the Keyfactor EJBCA Enterprise CLI.

  2. Install the Security World software. For detailed instructions, see the nShield Security World Software v13.9.3 Installation Guide.

  3. Add the Security World utilities path to the system path. This path is typically /opt/nfast/bin. Do so by creating the /etc/profile.d/nfast.sh file:

    $ cat /etc/profile.d/nfast.sh
# Entrust nShield HSM
export PATH=$PATH:/opt/nfast/bin

  4. Open firewall port 9004 for the Entrust nShield HSM connections. Alternatively, in AWS, add a TCP inbound/outbound rule connecting to the HSM to the EC2 security group.

    $ sudo firewall-cmd --permanent --add-port=9004/tcp
$ sudo firewall-cmd --reload

  5. If using Remote Administration, open firewall port 9005 for the Entrust nShield Trusted Verification Device (TVD). Alternatively, in AWS, add inbound and outbound TCP rules between the EC2 security group and the machine hosting the TVD.

  6. Run the enquiry utility to confirm the Security World is operational.

    $ /opt/nfast/bin/enquiry
Server:
 enquiry reply flags  none
 enquiry reply level  Six
 serial number
 mode                 operational
 version              13.6.14
 ...

Install the Entrust nShield HSM

Install the nShield Connect HSM locally, remotely, or remotely via the serial console. Condensed instructions are available in Entrust TrustedCare Portal.

For detailed instructions see the nShield v13.9.3 Hardware Install and Setup Guides.

Enroll the Entrust nShield HSM

  1. Inform the HSM of the client’s location.

    In this integration the client is the Keyfactor EJBCA Enterprise AWS EC2 instance. For instructions see Configuring the nShield HSM to use the client.

    If it is a high-availability setup, repeat the client configuration for each HSM.

  2. Enroll the Keyfactor EJBCA Enterprise AWS EC2 instance as a client of the HSM.

    For instructions see Configuring client computers to use the nShield HSM.

    If it’s a high-availability setup, repeat the enrollment for each HSM.

  3. Run the enquiry utility to confirm the HSM is operational:

    $ enquiry
Server:
 enquiry reply flags  none
 enquiry reply level  Six
 serial number        8FE1-B519-C5AA 6308-03E0-D947
 mode                 operational
 version              13.6.14
 ...
Module #1:
 enquiry reply flags  UnprivOnly
 enquiry reply level  Six
 serial number        8FE1-B519-C5AA
 mode                 operational
 version              13.4.5
 ...
 module type          nShield 5c
 ...
Module #2:
 enquiry reply flags  UnprivOnly
 enquiry reply level  Six
 serial number        6308-03E0-D947
 mode                 operational
 version              12.72.4
 ...
 module type          nShield Connect XC
 ...

Create a security world

  1. Create your Security World, if one does not already exist, or copy an existing one.

    Follow your organization’s security policy for this. For more information see Create a new Security World.

    ACS cards cannot be duplicated after the Security World is created. You may want to create extras in case of a card failure or a lost card.

  2. Confirm the Security World is Usable with nfkminfo:

    $ /opt/nfast/bin/nfkminfo
World
 generation  2
 state       0x37270008 Initialised Usable ...
 ...
Module #1
 generation 2
 state      0x2 Usable
 ...
Module #2
 generation 2
 state      0x2 Usable
 ...

Select the protection method

OCS, Softcard, or Module protection can be used to authorize access to the keys protected by the HSM. Typically, an organization’s security policies dictate the use of one of these methods.

  • Operator Cards Set (OCS) are smartcards that are presented to the physical smartcard reader of an HSM. For more information on OCS use, properties, and k-of-N values, see Operator Card Sets (OCS).

  • Softcards are logical tokens (passphrases) that protect the key and authorize its use. For more information on Softcard use, see Softcards.

  • Module protection has no passphrase.

Follow your organization’s security policy to select an authorization access method.

  1. Create the /opt/nfast/cknfastrc file containing the nShield PKCS #11 library environment variables per the selection above.

    For example:

    # Enable Softcard protection
CKNFAST_LOADSHARING=1

# Enable Module protection
CKNFAST_FAKE_ACCELERATOR_LOGIN=1

# OCS Preload file location and card set state
NFAST_NFKM_TOKENSFILE=/opt/nfast/preloadtoken
CKNFAST_NONREMOVABLE=1

# PKCS #11 log level and file location
CKNFAST_DEBUG=3
CKNFAST_DEBUGFILE=/opt/nfast/log/pkcs11.log

  2. Change ownership of the /opt/nfast/cknfastrc file to nfast:

    $ ls -al /opt/nfast/cknfastrc
-rw-rw-rw-. 1 root root 324 Apr  3 16:12 /opt/nfast/cknfastrc

$ sudo chown nfast:nfast /opt/nfast/cknfastrc

$ ls -al /opt/nfast/cknfastrc
-rw-rw-rw-. 1 nfast nfast 324 Apr  3 16:12 /opt/nfast/cknfastrc

  3. Make the /opt/nfast/log/pkcs11.log file writable:

    $ sudo touch /opt/nfast/log/pkcs11.log

$ sudo chmod 664 /opt/nfast/log/pkcs11.log

  4. Restart the nShield service:

    $ sudo /opt/nfast/sbin/init.d-ncipher restart
...

Create the OCS

  1. Edit the /opt/nfast/kmdata/config/cardlist file by adding the serial number of the cards to be presented or the wildcard "*".

  2. Run the createocs utility as described below, entering a passphrase at the prompt.

    Follow your organization’s security policy for the values K/N. Use the same passphrase for all the OCS cards in the set (one for each person with access privilege, plus the spares). In this example note that slot 2, remote via a TVD, is used to present the card.

    After an OCS card set has been created, the cards cannot be duplicated. You may want to create extras in case of a card failure or a lost card.
    The preload utility loads OCS onto the HSM. This feature makes the OCS available for use after being physically removed from the HSM for safe storage or other reasons. Add the -p (persistent) option to the command below to have authentication after the OCS card has been removed from the HSM front panel slot or from the TVD. 
    $ /opt/nfast/bin/createocs -m1 -s2 -N testOCS -Q 1/1

FIPS 140-2 level 3 auth obtained.

Creating Cardset:
 Module 1: 0 cards of 1 written
 Module 1 slot 0: Admin Card #1
 Module 1 slot 2: empty
 Module 1 slot 3: empty
 Module 1 slot 2: blank cardSteps:

 Module 1 slot 2:- passphrase specified - writing card
Card writing complete.

cardset created; hkltu = a165a26f929841fe9ff2acdf4bb6141c1f1a2eed

    In the example above, the authentication provided by the OCS is non-persistent and only available while the OCS card is inserted in the HSM front panel slot or the TVD.

  3. Verify the OCS using nfkminfo or rocs:

    nfkminfo
    $ /opt/nfast/bin/nfkminfo -c
Cardset list - 2 cardsets:  (P)ersistent/(N)ot, (R)emoteable/(L)ocal-only
 Operator logical token hash               k/n timeout  name
 edb3d45a28e5a6b22b033684ce589d9e198272c2  1/5  none-NL testOCS
    rocs
    $ /opt/nfast/bin/rocs
`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs> list cardset
No. Name                     Keys (recov) Sharing
  1 testOCS                  0 (0)        1 of 5
rocs> quit

Create the Softcard

  1. Enable Softcard protection as described in Select the protection method.

  2. Run the ppmk utility, and enter a passphrase at the prompt:

    $ /opt/nfast/bin/ppmk -n testSC
Enter new pass phrase:
Enter new pass phrase again:
New softcard created: HKLTU 644529aad18eeed9de372779e829f48757e617cd

  3. Verify the Softcard using nfkminfo or rocs:

    nfkminfo
    $ /opt/nfast/bin/nfkminfo -s
SoftCard summary - 1 softcards:
 Operator logical token hash               name
 644529aad18eeed9de372779e829f48757e617cd  testSC
    rocs
    $ /opt/nfast/bin/rocs
`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs> list cardsets
No. Name                     Keys (recov) Sharing
  1 testOCS                  0 (0)        1 of 5
  2 testSC                   0 (0)        (softcard)
rocs> quit