Create the Vault encryption and HMAC keys

The Vault encryption and HMAC keys can be protected with an OCS, Softcard, or Module. Key generation with all three protection methods is shown below. Choose the one that applies to you.

Verify the PKCS #11 library is available

  1. Present the OCS if using OCS protection.

  2. Execute the ckcheckinst command to test the library. Enter the slot number corresponding to the protection method used. Enter the OCS or Softcard passphrase when prompted.

    # ckcheckinst
PKCS#11 library interface version 2.40
                            flags 0
                   manufacturerID "nCipher Corp. Ltd               "
               libraryDescription "nCipher PKCS#11 13.6.8-209-a5bd9"
           implementation version 13.06
         Loadsharing and Failover enabled

Slot  Status            Label
====  ======            =====
   0  Fixed token       "loadshared accelerator          "
   1  Operator card     "testOCS                         "
   2  No token present
   3  Soft token        "testSC                          "

Select slot number to run library test or 'R'etry or to 'E'xit: 1
Using slot number 1.

Please enter the passphrase for this token (No echo set).
Passphrase:

Test                      Pass/Failed
----                      -----------

1 Generate RSA key pair   Pass
2 Generate DSA key pair   Pass
3 Encryption/Decryption   Pass
4 Signing/Verification    Pass

Deleting test keys         ok

PKCS#11 library test successful.

Create the keys using OCS protection

To create OCS protected keys in a FIPS 140-3 world, the OCS must be presented via the card reader in the HSM front panel. An alternative is to present the OCS remotely via the TVD while mapping the TVD slot to slot 0.

For example:

# cat /opt/nfast/kmdata/hsm-8FE1-B519-C5AA/config/config
syntax-version=1
...
[slot_mapping]
...
#
# ESN of the module on which slot 0 will be remapped with another.
#  esn=ESN
#
# Slot to exchange with slot 0. Setting this value to 0 means do
# nothing.(default=0)
#  slot=INT
esn=8FE1-B519-C5AA
slot=2
...

  1. Create the Vault encryption key vault_v1_ocs:

    # generatekey --generate --batch -m1 -s0 pkcs11 protect=token cardset=testOCS plainname=vault_v1_ocs type=AES size=256
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 protect      Protected by               token
 slot         Slot to read cards from    0
 recovery     Key recovery               yes
 verify       Verify security of key     yes
 type         Key type                   AES
 size         Key size                   256
 plainname    Key name                   vault_v1_ocs
 nvram        Blob in NVRAM (needs ACS)  no

Loading `testOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 0: `testOCS' #2
 Module 1 slot 2: empty
 Module 1 slot 3: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-d8ed4d73cfd90e4bf5c41c63459019e3382c1bbc

  2. Create the Vault HMAC key vault_hmac_v1_ocs:

    # generatekey --generate --batch -m1 -s0 pkcs11 protect=token cardset=testOCS plainname=vault_hmac_v1_ocs type=HMACSHA256 size=256
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 protect      Protected by               token
 slot         Slot to read cards from    0
 recovery     Key recovery               yes
 verify       Verify security of key     yes
 type         Key type                   HMACSHA256
 size         Key size                   256
 plainname    Key name                   vault_hmac_v1_ocs
 nvram        Blob in NVRAM (needs ACS)  no

Loading `testOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 0: `testOCS' #2
 Module 1 slot 2: empty
 Module 1 slot 3: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-3787adc4f5b499040058dcfdc0ad643e43817024

Create the keys using Softcard protection

  1. Create the Vault encryption key vault_v1_sc:

    # generatekey --generate --batch -m1 pkcs11 protect=softcard softcard=testSC plainname=vault_v1_sc type=AES size=256
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 protect      Protected by               softcard
 softcard     Soft card to protect key   testSC
 recovery     Key recovery               yes
 verify       Verify security of key     yes
 type         Key type                   AES
 size         Key size                   256
 plainname    Key name                   vault_v1_sc
 nvram        Blob in NVRAM (needs ACS)  no
Please enter the pass phrase for softcard `testSC':

Please wait........

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-408577c897946d66019d59cff232f989c57d6600

  2. Create the Vault HMAC key vault_hmac_v1_sc:

    # generatekey --generate --batch -m1 pkcs11 protect=softcard softcard=testSC plainname=vault_hmac_v1_sc type=HMACSHA256 size=256
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 protect      Protected by               softcard
 softcard     Soft card to protect key   testSC
 recovery     Key recovery               yes
 verify       Verify security of key     yes
 type         Key type                   HMACSHA256
 size         Key size                   256
 plainname    Key name                   vault_hmac_v1_sc
 nvram        Blob in NVRAM (needs ACS)  no
Please enter the pass phrase for softcard `testSC':

Please wait........

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-624d9f8e4e56dc281ce58b3b53dfb88772c9e88d

Create the keys using Module protection

  1. Create the Vault encryption key vault_v1_m:

    # generatekey --generate --batch -m1 pkcs11 protect=module plainname=vault_v1_m type=AES size=256
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 protect      Protected by               module
 verify       Verify security of key     yes
 type         Key type                   AES
 size         Key size                   256
 plainname    Key name                   vault_v1_m
 nvram        Blob in NVRAM (needs ACS)  no

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ua96a3d9e6dd69fba7c5a4df8a26f5dc4ccb2f5f79

  2. Create the Vault HMAC key vault_hmac_v1_m:

    # generatekey --generate --batch -m1 pkcs11 protect=module plainname=vault_hmac_v1_m type=HMACSHA256 size=256
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 protect      Protected by               module
 verify       Verify security of key     yes
 type         Key type                   HMACSHA256
 size         Key size                   256
 plainname    Key name                   vault_hmac_v1_m
 nvram        Blob in NVRAM (needs ACS)  no

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ua55376b64e163268e15e25670b0bab7f595d7a7c3

Verify the keys created

  1. Verify the keys created using the rocs utility:

    # rocs
`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs> list keys
  No. Name                     App        Protected by
    1 vault_v1_m               pkcs11     module
    2 vault_v1_ocs             pkcs11     testOCS
    3 vault_hmac_v1_ocs        pkcs11     testOCS
    4 vault_v1_sc              pkcs11     testSC (testSC)
    5 vault_hmac_v1_sc         pkcs11     testSC (testSC)
    6 vault_hmac_v1_m          pkcs11     module
rocs> exit

  2. Verify the keys created using the nfkminfo utility:

    # nfkminfo -l

Keys with module protection:
 key_pkcs11_ua55376b64e163268e15e25670b0bab7f595d7a7c3 `vault_hmac_v1_m'
 key_pkcs11_ua96a3d9e6dd69fba7c5a4df8a26f5dc4ccb2f5f79 `vault_v1_m'

Keys protected by softcards:
 key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-408577c897946d66019d59cff232f989c57d6600 `vault_v1_sc'
 key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-624d9f8e4e56dc281ce58b3b53dfb88772c9e88d `vault_hmac_v1_sc'

Keys protected by cardsets:
 key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-3787adc4f5b499040058dcfdc0ad643e43817024 `vault_hmac_v1_ocs'
 key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-d8ed4d73cfd90e4bf5c41c63459019e3382c1bbc `vault_v1_ocs'

Find the slot value for each protection method

Each protection method is loaded to a virtual slot of the HSM. The decimal value of this slot will be needed further down to configure Vault.

  1. Run the cklist utility. Notice the lines below.

    # cklist
Listing contents of slot 0
 (token label "loadshared accelerator          ")
...
Listing contents of slot 1
 (token label "testOCS                         ")
...
Skipping slot 2 (not present)
...
Listing contents of slot 3
 (token label "testSC                          ")
    loadshared accelerator

    Module protection.

    testOCS

    The name given to the OCS created in section install-entrust-hsm.adoc#create-ocs.

    testSC

    The name given to the Softcard token created in section install-entrust-hsm.adoc#create-softcard.

  2. Search file /opt/nfast/log/pkcs11.log for pSlotList. Notice the hex value for each slot. For example:

    ...
2025-04-03 17:23:26 [6544]: pkcs11: 00000000 <    pSlotList[0] 0x2D622495
2025-04-03 17:23:26 [6544]: pkcs11: 00000000 <    pSlotList[1] 0x2D622496
2025-04-03 17:23:26 [6544]: pkcs11: 00000000 <    pSlotList[2] 0x2D622497
2025-04-03 17:23:26 [6544]: pkcs11: 00000000 <    pSlotList[3] 0x2D622498
...

  3. Convert the pSlotList values to decimal:

    Protection Method Slot Number Value (Hex) Value (Decimal)

    Module

    0

    0x2D622495

    761406613

    OCS

    1

    0x2D622496

    761406614

    2

    0x2D622497

    761406615

    Softcards

    3

    0x2D622498

    761406616

    Save the decimal values.

    Adding or deleting Softcard tokens, or adding or deleting OCS, or adding or deleting Modules keys will change the values above. Redo the step to find the new values if necessary.