Integration Procedures

System preparation

  1. Open the firewall for HSM incoming connections:

    # sudo firewall-cmd --permanent --add-port=9004/tcp

  2. Open the firewall for HashiCorp Vault incoming connections:

    # sudo firewall-cmd --permanent --add-port=8200/tcp
# sudo firewall-cmd --permanent --add-port=8201/tcp

  3. Apply the firewall changes above:

    # sudo firewall-cmd --reload

  4. Install open-vm-tools:

    # sudo yum install open-vm-tools unzip opensc

Install the HSM

Install the nShield Connect HSM locally, remotely, or remotely via the serial console. See the following nShield Support articles, and the Installation Guide for the HSM:

Access to the Entrust nShield Support Portal is available to customers under maintenance. To request an account, contact nshield.support@entrust.com.

Install the Security World software and create a Security World

  1. Install and configure the Security World software. For instructions, see the Installation Guide and the User Guide for the HSM.

  2. When the Software has been installed, ensure that $NFAST_HOME is on the path:

    # 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”

  3. Restart the server.

  4. Confirm that the HSM is available:

    # enquiry

  5. Create your Security World if one does not already exist.

  6. Confirm that the Security World is operational and usable in the output of the nfkminfo command:

    # nfkminfo

Generate the keys with OCS and Softcard protection

The Vault seal key can be protected with an OCS, Softcard or Module:

  • Operator Cards Set (OCS) are smartcards that are presented to the physical smartcard reader of a HSM. If an OCS is used, k must = 1 whereas N can be up to, but not exceed, 64. For more information on OCS use, properties, and k-of-N values, see the User Guide for your HSM.

  • Softcards are logical tokens (passphrases) that protect they key and authorize its use.

  • Module protection has no passphrase.

Generate key using an OCS protection

  1. Create the OCS with example name and attributes, for 1-of-N (1/2 for a single-HSM configuration):

    # createocs -m1 -s2 -N HashiCorp -Q 1/1

  2. Create an encryption key vault_v1:

    # generatekey --generate --batch -m1 -s2 pkcs11 protect=token cardset=HashiCorp plainname=vault_v1 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
 nvram        Blob in NVRAM (needs ACS)  no

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

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucde4fa7e3ad8d66b6c652d18140b37bab9fe9d106-782f624f6eceb64a7515316d80a1c939b6e596e3

  3. Create the HMAC key vault_hmac_v1:

    # generatekey --generate --batch -m1 -s2 pkcs11 protect=token cardset=HashiCorp plainname=vault_hmac_v1 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
 nvram        Blob in NVRAM (needs ACS)  no

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

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucde4fa7e3ad8d66b6c652d18140b37bab9fe9d106-e0cd52a5b1eebb695a102fadf1ddb50e375ddcaf

Generate key using Softcard and Module protection

  1. Create a /opt/nfast/cknfastrc file with the following content:

    # cat /opt/nfast/cknfastrc
CKNFAST_LOADSHARING=1
CKNFAST_FAKE_ACCELERATOR_LOGIN=1
CKNFAST_DEBUG=10
CKNFAST_DEBUGFILE=/opt/nfast/log/pkcs11.log

    The first line enables Softcard protection support. The second enables Module protection support. Third and fourth enable PKCS11 log files which you will need to find the slot to configure the Vault.

  2. Create the Softcard token using the ppmk command. Enter a passphrase or password at the prompt.

    # ppmk -n vaultsc
Enter new pass phrase:
Enter new pass phrase again:
New softcard created: HKLTU Softcard_ID

  3. Create an encryption key vault_v1_sc using Softcard protection:

    # generatekey --generate --batch -m1 pkcs11 protect=softcard softcard=vaultsc 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   vaultsc
 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 `vaultsc':

Please wait........
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucb5df6e12703825562ce731e3286a4fb9f46e767a-ebc7da3d8e2f9aa86377dc4e5269157557cddd1c

  4. Create the HMAC key vault_hmac_v1_sc using Softcard protection:

    # generatekey --generate --batch -m1 pkcs11 protect=softcard softcard=vaultsc 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   vaultsc
 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 `vaultsc':

Please wait........
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucb5df6e12703825562ce731e3286a4fb9f46e767a-376268c6c89c1657fb22ca1f08fe4f20b58b1c07

  5. Verify the keys created:

    # rocs
`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs> list keys
  No. Name                     App        Protected by
    1 vault_v1                 pkcs11     HashiCorp
    2 vault_hmac_v1            pkcs11     HashiCorp
    3 vault_v1_sc              pkcs11     vaultsc (vaultsc)
    4 vault_hmac_v1_sc         pkcs11     vaultsc (vaultsc)
rocs> exit

  6. Create an encryption key vault_v1 and HMAC key vault_hmac_v1 using Module protection:

    # generatekey --generate --batch -m1 -s2 pkcs11 protect=module softcard=vaultsc plainname=vault_v1_m type=AES size=256
...
# generatekey --generate --batch -m1 -s2 pkcs11 protect=module softcard=vaultsc plainname=vault_hmac_v1_m type=HMACSHA256 size=256
...

Verify the PKCS#11 library is available

In the example below an Operator Card Set has been created with the name HashiCorp. The card is present in the physical slot (card reader) of the HSM, and is loaded to slot #1.

  1. Execute the ckcheckinst command to test the library:

    # ckcheckinst
PKCS#11 library interface version 2.01
                            flags 0
                   manufacturerID "nCipher Corp. Ltd               "
               libraryDescription "nCipher PKCS#11 12.60.11-837-510"
           implementation version 12.60
         Loadsharing and Failover enabled

Slot  Status            Label
====  ======            =====
   0  Fixed token       "loadshared accelerator          "
   1  Operator card     "HashiCorp                       "
   2  Soft token        "vaultsc                         "

  2. Select the slot number of the Operator card and press the Enter key:

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

  3. Enter the passphrase for the OCS:

    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.

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          ")
...
Listing contents of slot 1
 (token label "HashiCorp                       ")
...
Listing contents of slot 2
 (token label "vaultsc                         ")
    loadshared accelerator

    Module protection, that is slot 0.
    HashiCorp

    The name given to the OCS created above, slot 1.
    vaultsc

    The name given to the Softcard token created above, slot 2.

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

    ...
2021-02-05 12:53:36 [4866]: pkcs11: 00000000 <    pSlotList[0] 0x2D622495
2021-02-05 12:53:36 [4866]: pkcs11: 00000000 <    pSlotList[1] 0x2D622496
2021-02-05 12:53:36 [4866]: pkcs11: 00000000 <    pSlotList[2] 0x2D622497
...

  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.

Create Vault user and group

  1. Create the Vault group:

    # sudo groupadd --system vault

  2. Create the Vault user:

    # sudo useradd --system --shell /sbin/nologin --gid vault vault

  3. Add the Vault user to the nShield nfast group:

    # sudo usermod --append --groups nfast vault

Install Vault

  1. Download the Vault package from HashiCorp at https://releases.hashicorp.com/vault/, ensuring that it is the binary file for Enterprise with HSM support. For example:

    # wget https://releases.hashicorp.com/vault/1.9.2+ent.hsm/vault_1.9.2+ent.hsm_linux_amd64.zip
--2021-12-23 15:30:53--  https://releases.hashicorp.com/vault/1.9.2+ent.hsm/vault_1.9.2+ent.hsm_linux_amd64.zip
Resolving releases.hashicorp.com (releases.hashicorp.com)... 151.101.1.183, 151.101.65.183, 151.101.129.183, ...
Connecting to releases.hashicorp.com (releases.hashicorp.com)|151.101.1.183|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 69760875 (67M) [application/zip]
Saving to: 'vault_1.9.2+ent.hsm_linux_amd64.zip'

vault_1.9.2+ent.hsm_lin 100%[==============================>]  66.53M  10.7MB/s    in 6.2s

2021-12-23 15:30:59 (10.7 MB/s) - 'vault_1.9.2+ent.hsm_linux_amd64.zip' saved [69760875/69760875]

  2. Unzip the binary file and extract it to the working directory on the host machine, for example /usr/local/bin. There should only be a single binary file named vault_.

    # unzip vault_1.9.2+ent.hsm_linux_amd64.zip -d /usr/local/bin

  3. Set Vault permissions:

    # chmod 755 /usr/local/bin/vault
# setcap cap_ipc_lock=+ep /usr/local/bin/vault
# ls -la /usr/local/bin/vault
-rwxr-xr-x. 1 root root 137112792 Dec 18 09:06 /usr/local/bin/vault

  4. Add the Vault binary file to the path:

    # sudo vi /etc/profile.d/vault.sh

    Add the following information to vault.sh and save it.

    # HashiCorp Vault path variable
export PATH="$PATH:/usr/local/bin"
export VAULT_ADDR=http://127.0.0.1:8200

  5. Create the Vault data directories:

    # sudo mkdir --parents /opt/vault/data
# sudo mkdir --parents /opt/vault/logs
# sudo chmod --recursive 750 /opt/vault
# sudo chown --recursive vault:vault /opt/vault

  6. Restart the server.

  7. Confirm that the binary file is available:

    # vault version
Vault v1.9.2+ent.hsm (f7be55269a69543aedae108588e63688e6490b44) (cgo)

Install the Vault license

  1. Open a new terminal and create a directory for the Vault license and configuration files:

    # sudo mkdir /etc/vault

  2. Three options are given in https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?in=vault/enterprise for enabling an enterprise license, as well as a procedure to request a trail license. For this guide, create a file containing the enterprise license key.

    # cat /etc/vault/license.hclic
02MV4UU43BK5HGYYTOJZWFQMTMNNEWU33JLJDVCMKOGJDGQWSUIV2E6VCNGVMVGMBT...

Create a configuration file

Set up a /etc/vault/config.hcl configuration file to enable Vault to be run as a service. See also Vault commands.

An example configuration file for using Vault with OCS protection is shown below.

  • Refer to Find the slot value for each protection method for the slot value.

  • The entropy seal mode is set to augmentation. This leverages the HSM for augmenting system entropy via the PKCS#11 protocol.

  • The seal wrap is enabled. By enabling seal wrap, Vault wraps your secrets with an extra layer of encryption leveraging the HSM encryption and decryption.

  • Notice the path to the license file.

# PKCS#11 Seal, Entrust nShield Integration
seal "pkcs11" {
lib = "/opt/nfast/toolkits/pkcs11/libcknfast.so"
slot = "761406614"
pin = "ncipher"
key_label = "vault_v1"
hmac_key_label = "vault_hmac_v1"
# Vault should not generate the keys, the default
#generate_key = false
}
# Vault uses nCipher nShield for entropy augmentation
# This is an optional configuration
entropy "seal" {
mode = "augmentation"
}
# Vault listener with TLS disabled
listener "tcp" {
address = "0.0.0.0:8200"
tls_disable = true
}
storage "file" {
path = "/opt/vault/data"
}
# Seal Wrap is enabled, the Default,
# Entrust nShield is used to wrap the CSPs
#disable_sealwrap=false
ui = true
# License file
license_path = "/etc/vault/license.hclic"

The following is an example configuration file for using Vault with Softcard protection. Notice that the slot value changed from the OCS protection example above.

# PKCS#11 Seal, Entrust nShield Integration
seal "pkcs11" {
lib = "/opt/nfast/toolkits/pkcs11/libcknfast.so"
slot = "761406615"
pin = "ncipher"
key_label = "vault_v1_sc"
hmac_key_label = "vault_hmac_v1_sc"
# Vault should not generate the keys, the default
#generate_key = false
}
# Vault uses nCipher nShield for entropy augmentation
# This is an optional configuration
entropy "seal" {
mode = "augmentation"
}
# Vault listener with TLS disabled
listener "tcp" {
address = "0.0.0.0:8200"
tls_disable = true
}
storage "file" {
path = "/opt/vault/data"
}
# Seal Wrap is enabled, the Default,
# Entrust nShield is used to wrap the CSPs
#disable_sealwrap=false
ui = true
# License file
license_path = "/etc/vault/license.hclic"

Create and configure Vault directories

  1. Create a vault file in sysconfig:

    # touch /etc/sysconfig/vault

  2. Create a service file:

    # vi /etc/systemd/system/vault.service

  3. Add the following information to the file.

    If deploying on a server with more than two CPUs, you may increase the value of Environment=GOMAXPROCS accordingly.

    [Unit]
Description="HashiCorp Vault"
Requires=network-online.target
After=network-online.target nc_hardserver.service
ConditionFileNotEmpty=/etc/vault/config.hcl
[Service]
User=vault
Group=vault
EnvironmentFile=/etc/sysconfig/vault
ExecStart=/usr/local/bin/vault server -config=/etc/vault/config.hcl
StandardOutput=/opt/vault/logs/output.log
StandardError=/opt/vault/logs/error.log
ExecReload=/bin/kill --signal -HUP $MAINPID
KillMode=process
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
StartLimitInterval=60
StartLimitBurst=3
AmbientCapabilities=CAP_IPC_LOCK
LimitNOFILE=65536
LimitMEMLOCK=infinity
[Install]
WantedBy=multi-user.target

  4. If you are setting paths different from the default, you must edit the following lines as well in the configuration file:

    ConditionFileNotEmpty=/etc/vault/config.hcl
EnvironmentFile=-/etc/sysconfig/vault
ExecStart=/opt/vault/bin/vault server -config=/etc/vault/config.hcl
StandardOutput=/opt/vault/logs/output.log
StandardError=/opt/vault/logs/error.log

Enable Vault

  1. Set the following environment variable to allow Vault to be accessed from a web browser via the web user interface (web UI). Append the following line to the /etc/profile.d/vault.sh file created above, and restart the system.

    export VAULT_ADDR=http://127.0.0.1:8200

  2. Enable Vault:

    # systemctl enable vault.service

Start Vault

The HSM will be accessed as part of starting Vault. Therefore, the OCS or Softcard is needed.

  1. Start the Vault service:

    The OCS card created in section Generate key using an OCS protection must be inserted in the HSM slot if the protection method defined in /etc/vault/config.hcl is OCS protection. Otherwise the Vault will fail to start. The OCS card is not required for the Vault to start if the protection method is Softcard on Module.

    # systemctl start vault.service

  2. Check that the Vault service is running:

    # systemctl status vault.service
● vault.service - "HashiCorp Vault"
   Loaded: loaded (/etc/systemd/system/vault.service; enabled; vendor preset: disabled)
   Active: active (running) since Wed 2022-01-05 09:48:56 EST; 58min ago
 Main PID: 16120 (vault)
    Tasks: 7 (limit: 49193)
   Memory: 108.2M
   CGroup: /system.slice/vault.service
           └─16120 /usr/local/bin/vault server -config=/etc/vault/config.hcl

Jan 05 10:47:08 Red_Hat_8.3_HashiCorp_Containers vault[16120]: 2022-01-05T10:47:08.045-0500 [INFO] >
Jan 05 10:47:08 Red_Hat_8.3_HashiCorp_Containers vault[16120]: 2022-01-05T10:47:08.045-0500 [WARN] >
...

  3. Check the Vault status:

    # vault status
Key                      Value
---                      -----
Recovery Seal Type       pkcs11
Initialized              false
Sealed                   true
Total Recovery Shares    0
Threshold                0
Unseal Progress          0/0
Unseal Nonce             n/a
Version                  1.9.2+ent.hsm
Storage Type             file
HA Enabled               false

  4. Initialize the Vault:

    When using an HSM for auto unseal, Vault requires the number of key shares, threshold, and stored shares to be set to one (1).

    Use the following command options to initialize the Vault: recovery-shares=1 and recovery-threshold=1.

    The vault operator init command returns the Recovery Key(s) and Initial Root Token. Note or save these.

    # vault operator init -recovery-shares=1 -recovery-threshold=1
Recovery Key 1: 3zs1c7LEAs/hq8pvVYkcLX3wZ3hpqavtvNZvkjFhh7E=

Initial Root Token: s.Yl5MiQBmWC5JVpnL5fsRMkeM

Success! Vault is initialized

Recovery key initialized with 1 key shares and a key threshold of 1. Please
securely distribute the key shares printed above.

Log in from the command line

Log in to Vault using the Initial Root Token saved above and save the token below.

# vault login s.Yl5MiQBmWC5JVpnL5fsRMkeM
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                s.Yl5MiQBmWC5JVpnL5fsRMkeM
token_accessor       9opm7hJmNyTdMhFcttrww0u8
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

Log in from the web user interface

  1. Open a browser and enter the IP address of the Vault Host Server. For example:

    http://127.0.0.1:8200/ui/vault/auth

    The Vault sign-in page loads.

  2. Enter the sign-in credentials:

    1. For the Method drop-down list, select Token.

    2. In the Token field, enter the Initial Root Token that you saved after you started Vault.

    3. Select Sign In.

      The Secrets Engines page appears. The Status light should be green. For example:

      Secrets Engines

  3. Select Status to check the details. The Vault should be Unsealed. For example:

    Status

Examine Vault secrets

Use the Secrets Engine operations of the Vault to check whether the integration works as intended. You can use these commands to generate, encrypt, and store any secret in a secure storage area, for example in a cubbyhole or in a key/value (KV) storage location.

View the current secrets and default locations.

vault secrets list
Path          Type         Accessor              Description
----          ----         --------              -----------
cubbyhole/    cubbyhole    cubbyhole_ddaf9cb7    per-token private secret storage
identity/     identity     identity_62a1922c     identity store
sys/          system       system_fbaaf933       system endpoints used for control, policy and debugging

Enable the KV engine

To enable the KV engine:

$ vault secrets enable -version=1 kv
Success! Enabled the kv secrets engine at: kv/

Write secret data

Add data to the key/value storage area of Vault:

$ vault kv put kv/opt/vault/secret key=test_secret
Success! Data written to: kv/opt/vault/secret

Retrieve secret data

To retrieve secret data:

$ vault kv get kv/opt/vault/secret
=== Data ===
Key    Value
---    -----
key    test_secret

Seal Vault

When you are done, seal Vault:

# vault operator seal
Success! Vault is sealed.

Rotate keys stored in the HSM and used by Vault

  1. Create new HSM-protected Vault keys:

    Using OCS protection

    1. Create a new encryption key vault_v2:

      # generatekey --generate --batch -m1 -s2 pkcs11 protect=token cardset=HashiCorp plainname=vault_v2 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_v2
 nvram        Blob in NVRAM (needs ACS)  no

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

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucde4fa7e3ad8d66b6c652d18140b37bab9fe9d106-ea26282514f5701358c1c90c983f39e1e86d9292

    2. Create a new HMAC key vault_hmac_v2:

      # generatekey --generate --batch -m1 -s2 pkcs11 protect=token cardset=HashiCorp plainname=vault_hmac_v2 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_v2
 nvram        Blob in NVRAM (needs ACS)  no

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

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucde4fa7e3ad8d66b6c652d18140b37bab9fe9d106-569f841f569cafa49abcc0bb5308aef67f62df19

    Using Softcard protection

    1. Create a new encryption key vault_v2:

      # generatekey --generate --batch -m1 pkcs11 protect=softcard softcard=vaultsc plainname=vault_v2 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   vaultsc
 recovery     Key recovery               yes
 verify       Verify security of key     yes
 type         Key type                   AES
 size         Key size                   256
 plainname    Key name                   vault_v2
 nvram        Blob in NVRAM (needs ACS)  no
Please enter the pass phrase for softcard `vaultsc':

Please wait........
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uca4c30a628024194c2c44b579ab54088f2baa5964-6274a79faa4cb7ce8f7f9bade9fb1bd4240caee1

    2. Create a new HMAC key vault_hmac_v2:

      # generatekey --generate --batch -m1 pkcs11 protect=softcard softcard=vaultsc plainname=vault_hmac_v2 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   vaultsc
 recovery     Key recovery               yes
 verify       Verify security of key     yes
 type         Key type                   HMACSHA256
 size         Key size                   256
 plainname    Key name                   vault_hmac_v2
 nvram        Blob in NVRAM (needs ACS)  no
Please enter the pass phrase for softcard `vaultsc':

Please wait........
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uca4c30a628024194c2c44b579ab54088f2baa5964-5ae8f9fd29813f900eb9602558677d6ed9bbdcd2

  2. Update the Vault configuration:

    # sudo vi /etc/vault/config.hcl

    Update the _v1 version in the following lines to _v2:

    • key_label = "vault_v2"

    • hmac_key_label = "vault_hmac_v2"

  3. Restart Vault:

    # systemctl restart vault.service

  4. Log in to Vault, as a user with rewrap permission:

    # vault login
Token (will be hidden):
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                s.Yu94RNC8nHtGD4MUT0REa12G
token_accessor       dGjokkWequ2IFU260Jwanw7b
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

  5. Rewrap all.

    Optionally, use Seal Wrapped Data. Lazy rewrap is the default.

    # vault write -f /sys/sealwrap/rewrap
Success! Data written to: sys/sealwrap/rewrap

  6. Check the rewrap status:

    # vault read /sys/sealwrap/rewrap
Key           Value
---           -----
entries       map[failed:0 processed:24 succeeded:24]
is_running    false

Change protection method

The protection method cannot be changed after Vault has been initialized. You can change keys within the same protection method without re-initializing the Vault, but not the protection method.

Changing the appropriate parameters in /etc/vault/config.hcl and re-starting the Vault causes a CKR_KEY_HANDLE_INVALID error.

The following steps were done for the purpose of integration testing. This will allow re-initialization of Vault, but will destroy all secrets in a previously initialized Vault.

  1. Prepare the Vault for re-initialization:

    # systemctl stop vault.service
# userdel vault
# groupdel -f vault
# rm -r -f /opt/vault/data/*
# rm -r -f /opt/vault/logs/*
# touch /etc/sysconfig/vault
# touch /etc/systemd/system/vault.service

  2. Edit the /etc/vault/config.hcl file per the new protection method. Change the parameters slot, key_label, hmac_key_label accordingly.

  3. Reboot the client.

  4. Create new vault user and group, re-initialize the Vault, and do the integration as described above.