Create the Vault encryption and HMAC keys

Follow these steps to create the Vault keys with a single HSM:

  1. Create the keys using an OCS protection

  2. Create the keys using Softcard protection

  3. Create the keys using Module protection

  4. Find the slot value for each protection method

The Vault encryption and HMAC keys can be protected with an OCS, Softcard, or Module: Key generation with all three protection methods are shown below. Choose those that apply to you.

Create the keys using an OCS protection

  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    2
 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: Admin Card #15
 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-3ea7edc9ff8a7c2b17401920b12a3a67a3e21dd7

  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    2
 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: Admin Card #15
 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-5e0252dea777e36934160cbd072bf03cd1e9ba70

Create the keys using Softcard protection

  1. Create the 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-cdd81cd59c7a4a8518cdcc6c2b7beeac4a88c340

  2. Create the 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-6c07551e82281c8cc6a531d12c934701409d42be

Create the keys using Module protection

  1. Create the 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_uab23eff123cdbd108ff958fae07b12c1da92762dc

  2. Create the 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_ua47626b663321b99fb7ce1d035bb211a5311abf0f

  3. 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_ocs             pkcs11     testOCS
    2 vault_hmac_v1_ocs        pkcs11     testOCS
    3 vault_v1_sc              pkcs11     testSC (testSC)
    4 vault_hmac_v1_sc         pkcs11     testSC (testSC)
    5 vault_v1_m               pkcs11     module
    6 vault_hmac_v1_m          pkcs11     module
rocs> exit

  4. Verify the keys created using the nfkminfo utility.

    # nfkminfo -l

Keys with module protection:
 key_pkcs11_ua47626b663321b99fb7ce1d035bb211a5311abf0f `vault_hmac_v1_m'
 key_pkcs11_uab23eff123cdbd108ff958fae07b12c1da92762dc `vault_v1_m'

Keys protected by softcards:
 key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-6c07551e82281c8cc6a531d12c934701409d42be `vault_hmac_v1_sc'
 key_pkcs11_uc925f67e72ea3c354cae4e6797bde3753d24e7744-cdd81cd59c7a4a8518cdcc6c2b7beeac4a88c340 `vault_v1_sc'

Keys protected by cardsets:
 key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-3ea7edc9ff8a7c2b17401920b12a3a67a3e21dd7 `vault_v1_ocs'
 key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-5e0252dea777e36934160cbd072bf03cd1e9ba70 `vault_hmac_v1_ocs'

Verify the PKCS#11 library is available

  1. Present the OCS. Use the nfkminfo utility to find the slot number of the OCS.

    # nfkminfo
World
 generation  2
 state       0x3737000c Initialised Usable ...
...
Module #1 Slot #0 IC 161
 generation    1
 phystype      SmartCard
 slotlistflags 0x180002 SupportsAuthentication DynamicSlot Associated
 state         0x5 Operator
 flags         0x10000
 shareno       2
 shares        LTU(PIN) LTFIPS
 error         OK
Cardset
 name          "testOCS"
 k-out-of-n    1/5
 flags         NotPersistent PINRecoveryForbidden(disabled) !RemoteEnabled
 timeout       none
 card names    "" "" "" "" ""
 hkltu         edb3d45a28e5a6b22b033684ce589d9e198272c2
 gentime       2023-07-20 18:50:48
 ...

  2. Execute the ckcheckinst command to test the library. Enter the slot number above when prompted. Enter the OCS passphrase when prompted.

    # ckcheckinst
PKCS#11 library interface version 2.40
                            flags 0
                   manufacturerID "nCipher Corp. Ltd               "
               libraryDescription "nCipher PKCS#11 13.4.4-379-58f7e"
           implementation version 13.04
         Loadsharing and Failover enabled

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

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

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.

Find the slot value for each protection method

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

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

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

    Module protection (slot 0).

    testOCS

    The name given to the OCS created above (slot 2).

    testSC

    The name given to the Softcard token created above (slot 3).

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

    ...
2023-10-13 13:04:19 [28493]: pkcs11: 00000000 <    pSlotList[0] 0x1D622495
2023-10-13 13:04:19 [28493]: pkcs11: 00000000 <    pSlotList[1] 0x1D622496
2023-10-13 13:04:19 [28493]: pkcs11: 00000000 <    pSlotList[2] 0x1D622497
...

  3. Convert to decimal:

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

    Module

    0

    0x2D622495

    761406613

    OCS

    1

    0x2D622496

    761406614

    Softcards

    2

    0x2D622497

    761406615

    Note or 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.