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.14-390-0ff9"
           implementation version 13.06
         Loadsharing and Failover enabled

Slot  Status            Label
====  ======            =====
   0  Fixed token       "loadshared accelerator          "
   1  Fixed token       "testOCS                         "
   2  Soft token        "testSC                          "


No removable tokens present.
Please insert an operator card into at least one available slot and enter 'R' retry.
If you have not created an operator card or there are no physical slots,
 enter a fixed token slot number,
 or 'E' to exit this program and create a card set before continuing.

Enter a fixed token slot number, 'R'etry or 'E'xit: 2
Using slot number 2.

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, 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.

In a FIPS 140-3 world the TVD slot needs to be mapped 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_encript_key_ocs:

    # generatekey --generate --batch -m 1 pkcs11 type=AES size=256 protect=token cardset=testOCS plainname=vault_encript_key_ocs
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 module       Module to use              2
 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_encript_key_ocs
 nvram        Blob in NVRAM (needs ACS)  no

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

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

  2. Create the Vault HMAC key vault_hmac_key_ocs:

    # generatekey --generate --batch -m 1 pkcs11 type=HMACSHA256 size=256 protect=token cardset=testOCS plainname=vault_hmac_key_ocs
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 module       Module to use              2
 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_key_ocs
 nvram        Blob in NVRAM (needs ACS)  no

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

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

Create the keys using Softcard protection

  1. Create the Vault encryption key vault_encript_key_sc:

    # generatekey --generate --batch -m 1 pkcs11 type=AES size=256 protect=softcard cardset=testSC plainname=vault_encript_key_sc
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 module       Module to use              1
 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_encript_key_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-4f96d0a4884c80c13516d5b2464698413dd49d91

  2. Create the Vault HMAC key vault_hmac_key_sc:

    # generatekey --generate --batch -m 1 pkcs11 type=HMACSHA256 size=256 protect=softcard softcard=testSC plainname=vault_hmac_key_sc
key generation parameters:
 operation    Operation to perform       generate
 application  Application                pkcs11
 module       Module to use              1
 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_key_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-82f86ff15af96aea4ff7ab5662648403aa826101

Create the keys using Module protection

  1. Create the Vault encryption key vault_encript_key_m:

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

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

  2. Create the Vault HMAC key vault_hmac_key_m:

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

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

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 key
  No. Name                     App        Protected by
    1 vault_encript_key_sc     pkcs11     testSC (testSC)
    2 vault_hmac_key_sc        pkcs11     testSC (testSC)
    3 vault_encript_key_m      pkcs11     module
    4 vault_hmac_key_m         pkcs11     module
    5 vault_encript_key_ocs    pkcs11     testOCS
    6 vault_hmac_key_ocs       pkcs11     testOCS
rocs> quit

  2. Verify the keys created using the nfkminfo utility:

    # # nfkminfo -l

Keys with module protection:
 key_pkcs11_ua41efc7f818447bf26d6e6d75c2974e9ddb6d0759 `vault_hmac_key_m'
 key_pkcs11_ua668a069f094a62eb7ff72e31f466cd7f643a0346 `vault_encript_key_m'

Keys protected by softcards:
 key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-4f96d0a4884c80c13516d5b2464698413dd49d91 `vault_encript_key_sc'
 key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-82f86ff15af96aea4ff7ab5662648403aa826101 `vault_hmac_key_sc'

Keys protected by cardsets:
 key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-0d87f2c32b88359ad60e0e51c9039ad5eab20488 `vault_hmac_key_ocs'
 key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-bacbe490ce0e4fe82b4612195476bf070fb6660c `vault_encript_key_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                         ")
...
Listing contents of slot 2
 (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:

    # cat /opt/nfast/log/pkcs11.log | grep pSlotList
...
2025-12-22 13:37:50 [2848]: pkcs11: 00000000 <    pSlotList[0] 0x2D622495
2025-12-22 13:37:50 [2848]: pkcs11: 00000000 <    pSlotList[1] 0x2D622496
2025-12-22 13:37:50 [2848]: pkcs11: 00000000 <    pSlotList[2] 0x2D622497
...

  3. Convert the pSlotList values to decimal:

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

    Module

    0

    0x2D622495

    761406613

    OCS

    1

    0x2D622496

    761406614

    Softcards

    2

    0x2D622497

    761406615

    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.