Install and configure the Entrust nShield HSM

Install the Entrust nShield HSM

Install the HSM locally, remotely, or remotely via the serial console. Condensed instructions are available in the following Entrust nShield Support articles.

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

Install the Security World software and create a Security World

Install the Security World software. For detailed instructions see the nShield Security World Software v13.6.8 Installation Guide.
Add the Security World utilities path to the system path. This path is typically /opt/nfast/bin:
```
# sudo vi /etc/profile.d/nfast.sh
```
Add the following info to nfast.sh and save:
```
# Entrust Security World path variable
export PATH=$PATH:/opt/nfast/bin
```

Open firewall port 9004 for the HSM connections:

# sudo firewall-cmd --permanent --add-port=9004/tcp
[sudo] password for sysadmin:
success
# sudo firewall-cmd --reload
success

If using remote administration, open firewall port 9005 for the Entrust nShield Trusted Verification Device (TVD). Otherwise skip this step.
```
# sudo firewall-cmd --permanent --add-port=9005/tcp
[sudo] password for sysadmin:
success
# sudo firewall-cmd --reload
success
```

Open a command window and run the following utility to confirm that the HSM is operational:

>enquiry
Server:
 enquiry reply flags  none
 enquiry reply level  Six
 serial number        8FE1-B519-C5AA
 mode                 operational
...
Module #1:
 enquiry reply flags  UnprivOnly
 enquiry reply level  Six
 serial number        8FE1-B519-C5AA
 mode                 operational
...

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.

This is an example of the steps to copy an existing world from another server. The world and module files were first copied to the /home/sysadmin/Download directory from an external machine. Then these were copied to the /opt/nfast/kmdata/local directory. Notice the ownership.

[sysadmin@timestamping-auth-edm local]$ ls -al /home/sysadmin/Downloads/world
-rw-r-----. 1 sysadmin edm 40860 Nov  6  2024 /home/sysadmin/Downloads/world
[sysadmin@timestamping-auth-edm local]$ ls -al /home/sysadmin/Downloads/module_8FE1-B519-C5AA
-rw-r-----. 1 sysadmin edm 3716 Apr  2 15:14 /home/sysadmin/Downloads/module_8FE1-B519-C5AA

[sysadmin@timestamping-auth-edm local]$ sudo cp /home/sysadmin/Downloads/world /opt/nfast/kmdata/local/.
[sudo] password for sysadmin:
[sysadmin@timestamping-auth-edm local]$ sudo cp /home/sysadmin/Downloads/module_8FE1-B519-C5AA /opt/nfast/kmdata/local/.
[sudo] password for sysadmin:

[sysadmin@timestamping-auth-edm local]$ ls -al /opt/nfast/kmdata/local/
total 52
drwxrwsr-x. 2 nfast nfast  4096 May  9 09:52 .
drwxrwsr-x. 7 nfast nfast  4096 May  8 17:13 ..
-rw-r-----. 1 root  nfast  3716 May  9 09:52 module_8FE1-B519-C5AA
-rw-r-----. 1 root  nfast 40860 May  9 09:40 world

Confirm that the Security World is "Usable*:

> nfkminfo
World
 generation  2
 state       0x3737000c Initialised Usable ...
 ...
Module #1
 generation 2
 state      0x2 Usable
 ...

== Select the protection method

The OCS or Softcard and associated passphrase will be used to authorize access to specific keys protected by the HSM.

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 they key and authorize its use. For more information on Softcards use see Softcards.

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

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

# Enable Softcard protection
CKNFAST_LOADSHARING=1

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

# PKCS #11 log level
CKNFAST_DEBUG=10

The Kubernetes implementation of the TSA puts some restrictions in the location of the preloadtoken file. Also the PKCS #11 log traditionally written to /opt/nfast/log/pkcs11.log will now be available as described in Troubleshoot. Some log info is also written to /var/log/entrust/tsa/tsactl.log. These log contains both the PKCS #11 and TSA log info intertwined.

Change group ownership of /opt/nfast/cknfastrc to nfast.

[sysadmin@timestamping-auth-edm log]$ sudo chown root:nfast /opt/nfast/cknfastrc

Create the Operator Card Set (OCS) or Softcard

Typically, an organization’s security policies dictate the use of one or the other.

Create the OCS

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.
Add the -p (persistent) option to the createocs command to be able to encrypt/decrypt the database after the OCS card has been removed for safe storage from either the HSM front panel slot or from the TVD. See the Preload Utility for more information.
Recovering from a power failure requires the OCS to be inserted in the HSM or the TVD.
The authentication provided by the OCS as shown in the command in this section is non-persistent and only available while the OCS card is inserted in the HSM front panel slot or the TVD. If the TVD loses connection to the Remote Administration client the HSM will be inaccessible.

The Entrust Timestamping Authority maps one protecting token to one stored passphrase. It can store information for only one token at a time. Therefore an OCS card set quorum K must be one.

Edit file /opt/nfast/kmdata/config/cardlist to add the serial number of the card(s) to be presented or the wildcard value.

Run the createocs utility as described below. Enter a passphrase or password at the prompt. 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.

> 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: blank card
 Module 1 slot 3: empty
 Module 1 slot 2:- passphrase specified - writing card
Card writing complete.

cardset created; hkltu = edb3d45a28e5a6b22b033684ce589d9e198272c2

Verify the OCS created:

> nfkminfo -c
Cardset list - 1 cardsets:  (P)ersistent/(N)ot, (R)emoteable/(L)ocal-only
 Operator logical token hash               k/n timeout  name
 edb3d45a28e5a6b22b033684ce589d9e198272c2  1/1  none-NL testOCS

Create the Softcard

The Entrust Timestamping Authority maps one protecting token to one stored passphrase. Softcards are singular and do not have a quorum, so the Entrust Timestamping Authority credential matches them quite well.

Unlike OCS protection, which requires a smart card and a passcode, a softcard does not require additional input for recovery after a power failure.

Verify the /opt/nfast/cknfastrc file exists and contains the following variable. Otherwise, create it.
```
# Enable Softcard protection
CKNFAST_LOADSHARING=1
```

Execute the following command. Enter a passphrase at the prompt.

> ppmk -n testSC

Enter new pass phrase:
Enter new pass phrase again:
New softcard created: HKLTU 925f67e72ea3c354cae4e6797bde3753d24e7744

Verify the Softcard created:

> nfkminfo -s
SoftCard summary - 1 softcards:
 Operator logical token hash               name
 925f67e72ea3c354cae4e6797bde3753d24e7744  testSC

The rocs utility shows the OCS and Softcard created:

> 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
  2 testSC                   0 (0)        (softcard)
rocs> quit

Prepare files to be loaded into TSA

Copy the /opt/nfast/cknfastrc file to /opt/nfast/kmdata/.

[sysadmin@timestamping-auth-edm ~]$ sudo cp /opt/nfast/cknfastrc /opt/nfast/kmdata/.

Create the /tmp/preloadtoken file described in [select-protection-method] /opt/nfast/cknfastrc file. Change ownership to nfast.

[sysadmin@timestamping-auth-edm ~]$ sudo touch /tmp/preloadtoken
[sudo] password for sysadmin:

[sysadmin@timestamping-auth-edm ~]$ sudo chown nfast:nfast /tmp/preloadtoken

Change the permissions of directory /var/log/entrust/tsa containing the PKCS #11 log info.
```
[sysadmin@timestamping-auth-edm entrust]$ sudo chmod 777 /var/log/entrust/tsa
```

Add the sysadmin user to the nfast group.

[sysadmin@timestamping-auth-edm nfast]$ sudo usermod -a -G nfast sysadmin
[sudo] password for sysadmin: