Configure the Futurex PKCS #11 Library with HashiCorp Vault

The Vault HSM auto-unseal and Seal Wrap features require Vault Enterprise with the Governance and Policy Module.

To configure the Futurex PKCS #11 Library for use with HashiCorp Vault, perform the following tasks:

Download Vault.
Install Vault.
Configure Systemd.
Configure Vault settings.
Start the Vault server.
Enable and test the Seal Wrap feature.
Enable and test the Entropy Augmentation feature.

Download Vault

Download precompiled Vault binaries at https://releases.hashicorp.com/vault/. You can download Vault Enterprise binaries by following the instructions made available to HashiCorp Vault customers. This integration requires the Enterprise HSM binary. You can use this for testing and find it at the following link: https://releases.hashicorp.com/vault/1.7.2+ent.hsm/

Install Vault

Perform the following steps to install Vault:

Unzip the downloaded package and move the vault binary to /usr/local/bin/.

Shell

 unzip vault_${VAULT_VERSION}+ent.hsm_linux_amd64.zip

Set the owner of the Vault binary.

Shell

sudo chown root:root vault

Check that vault is available on the system path.

Shell

sudo mv vault /usr/local/bin/

Verify the Vault version.

Shell

vault --version

Enable autocompletion flags, subcommands, and arguments (where supported).

Shell

vault -autocomplete-install

Enable autocompletion.

Shell

complete -C /usr/local/bin/vault vault

Give Vault the ability to use the mlock syscall without running the process as root. The mlock syscall prevents the system from swapping memory to disk.

Shell

sudo setcap cap_ipc_lock=+ep /usr/local/bin/vault

Create a unique, non-privileged system user to run Vault.

Shell

sudo useradd --system --home /etc/vault.d --shell /bin/bash vault

Configure Systemd

Systemd uses documented sane defaults (www.freedesktop.org/software/systemd/man/systemd.directives.html), so you must set only non-default values in the configuration file.

Create a Vault service file at /etc/systemd/system/vault.service.

Shell

sudo touch /etc/systemd/system/vault.service

Add the following configuration to the Vault service file:

None

[Unit]
Description="HashiCorp Vault - A tool for managing secrets"
Documentation=https://www.vaultproject.io/docs/
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/vault.d/vault.hcl
StartLimitIntervalSec=60
StartLimitBurst=3

[Service]
User=vault
Group=vault
ProtectSystem=full
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK
Capabilities=CAP_IPC_LOCK+ep
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
NoNewPrivileges=yes
ExecStart=/usr/local/bin/vault server -config=/etc/vault.d/vault.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
StartLimitInterval=60
StartLimitIntervalSec=60
StartLimitBurst=3
LimitNOFILE=65536
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target

Configure Vault settings

This section shows you how to perform the following tasks:

Configure Vault
Configure Auto-unseal and Entropy Augementation.

Configure Vault

Vault uses documented sane defaults, so you must set only non-default values in the configuration file.

Create /etc/vault.d directory.

Shell

sudo mkdir --parents /etc/vault.d

Create a Vault configuration file, vault.hcl.

Shell

sudo touch /etc/vault.d/vault.hcl

Set the ownership of the /etc/vault.d directory.

Shell

sudo chown --recursive vault:vault /etc/vault.d

Set the file permissions.

Shell

sudo chmod 640 /etc/vault.d/vault.hcl

Configure HSM Auto-unseal and Entropy Augmentation

When you start a Vault server, it normally starts in a sealed state where you need a quorum of existing unseal keys to unseal it. By integrating Vault with an HSM, you can set the Vault server to be automatically unsealed by the trusted HSM key provider. To integrate the Vault Enterprise server with an HSM cluster, the configuration file must define the PKCS11 seal stanza (www.vaultproject.io/docs/configuration/seal/pkcs11.html) providing necessary connection information, as shown in the following example: Example: vault.hcl

Text

  # Provide your Futurex HSM connection information
  seal "pkcs11" {
     lib = "/usr/local/bin/fxpkcs11/x64/OpenSSL-1.1.x/libfxpkcs11.so"
     slot = "0"
     key_label = "hsm_demo"
     hmac_key_label = "hsm_hmac_demo"
     generate_key = "true"
  }

  # Add the entropy stanza
  entropy "seal" {
     mode = "augmentation"
  }

  # Configure the storage backend for Vault
  storage "file" {
     path = "/tmp/vault"
  }

  # Addresses and ports on which Vault will respond to requests
  listener "tcp" {
     address       = "0.0.0.0:8200"
     tls_disable   = "true"
  }

  ui = true
  disable_mlock = true

This guide sets the storage backend to the local file system, /tmp/vault, to make the verification step easy.

The example configuration defines the following in its seal stanza:

Parameter	Description
lib	Path to the PKCS #11 library on the machine where Vault Enterprise is installed.
slot	The slot number to use (this should be set to 0 because that is the default slot in the FXPKCS11 config file).
key_label	Defines the label of the key to use.
hmac_key_label	Defines the label of the key to use for HMACing.
generate_key	If no existing key with the label specified by key_label exists at Vault initialization time, Vault generates a key.

For this integration, the generate\key parameter needs to be set to true so that Vault automatically creates the encryption keys that it uses for the Seal Wrap functionality on the HSM. The values set for the key\label and hmac\key\label parameters correspond with the special key label defines that must be set in the <CONFIG> section of the fxpkcs11.cfg file

For the full list of configuration parameters, refer to the following Vault documentation: www.vaultproject.io/docs/configuration/seal/pkcs11.html#pkcs11-parameters.

Start the Vault Server

This section shows you haw to perform the following tasks:

Start Vault
Initialize Vault
Access the Vault UI

Start Vault

Perform the following steps to start Vault:

Set the PKCS #11 PIN for login with the following command. For the value of VAULT_HSM_PIN, use the password of the identity created on the HSM and defined in the FXPKCS11 config file.

Shell

export VAULT_HSM_PIN='safest'

You can also set the PKCS #11 PIN in the Vault configuration file (vault.hcl) with the pin parameter, but we don’t recommend this in a production setting. Best practice is to specify the PIN with the VAULT\HSM\PIN environment variable, as shown here. This prevents the password from being exposed if the config file is compromised or you store it in an insecure location. If set through the environment variable, Vault obfuscates the environment variable after reading it. The one caveat is that you must reset the VAULT\HSM\PIN environment variable if you restart the Vault.

Now, start the Vault server with the following command.

Shell

vault server -config=/etc/vault.d/vault.hcl

If this command is successful, you should see output similar to the following example:

Shell

==> Vault server configuration:
     HSM PKCS#11 Version: 2.20
             HSM Library: FxPKCS11
     HSM Library Version: 4.23
     HSM Manufacturer ID: Futurex
                HSM Type: pkcs11
                     Cgo: enabled
              Go Version: go1.14.4
              Listener 1: tcp (addr: "0.0.0.0:8200", cluster address: "0.0.0.0:8201", maxrequestduration: "1m30s", maxrequestsize: "33554432", tls: "disabled")
               Log Level: info
                   Mlock: supported: true, enabled: false
           Recovery Mode: false
                 Storage: file
                 Version: Vault v1.5.0+ent.hsm
==> Vault server started! Log data will stream in below:

Open a new terminal window and leave the terminal running where you started the Vault server.

Initialize Vault

Perform the following steps to initialize Vault:

In the new terminal, first, set the VAULT_ADDR environment variable.

Shell

export VAULT_ADDR='http://0.0.0.0:8200'

Check the Vault status.

Shell

vault status

The output should be similar to the following:

Shell

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                  n/a
HA Enabled               false

Initialize Vault.

Shell

vault operator init -recovery-shares=1 -recovery-threshold=1

The output should be similar to the following:

Shell

Recovery Key 1: E22HrXUFAyQy0PVUy+renVPXoLZ0bSRjWAsTZ64rE24=

Initial Root Token: s.mvX8cihrFqMWEiM9YFnlw9E1

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.

Set the VAULT_TOKEN environment variable value to the generated Root Token value displayed in the terminal output. To interact with Vault, you must provide a valid token. Setting this environment variable enables interaction with Vault through the CLI.

Shell

export VAULT_TOKEN="s.mvX8cihrFqMWEiM9YFnlw9E1"

Access the Vault UI

Perform the following steps to access the Vault UI:

Go to http://localhost:8200 in a web browser.

Copy and paste the Initial Root Token from the output of the Vault initialization command into the Token field, and select [ Sign In ].

If the login succeeds, you see the Vault UI homepage.

Enable and test the Seal Wrap feature

To enable and test the Seal Wrap feature, perform the tasks in this section.

Enable Seal Wrap

To enable Seal Wrap, choose the appropriate method and perform the instructions:

Use the CLI command

Perform the following steps to use the CLI command method to enable Seal Wrap:

To compare seal-wrapped data against unwrapped data, enable key/value v1 secrets engine at two different paths: kv-unwrapped and kv-seal-wrapped.Enable k/v v1 without seal wrap at kv-unwrapped.

Shell

vault secrets enable -path=kv-unwrapped kv

Enable k/v v1 with seal wrap. To do so, use the -seal-wrap flag when you enable the KV workflow.

Shell

vault secrets enable -path=kv-seal-wrapped -seal-wrap kv

To enable seal wrap, pass the -seal-wrap flag when you enable a secrets engine.

List the enabled secrets engines with details.

Shell

$ vault secrets list -detailed

Path                Plugin       Accessor              ...    Seal Wrap    ...
----                ------       --------                     -----------  ...
cubbyhole/          cubbyhole    cubbyhole_b36dd7e1    ...    false        ...
identity/           identity     identity_b5650a96     ...    false        ...
kv-seal-wrapped/    kv           kv_fe02767b           ...    true         ...
kv-unwrapped/       kv           kv_36d321c6           ...    false        ...
...

Notice that the Seal Wrap parameter value is true for kv-unwrapped/.

Use the Web UI

Perform the following steps to use the Web UI method to enable Seal Wrap:

Open a web browser and launch the Vault UI (for example, http://127.0.0.1:8200/ui) and then log in.

Select Secrets engines in the left menu.

Select [ Enable new engine ].

Select KV from the list and then select [ Next ].

Enter kv-unwrapped in the path field and select [ Enable new engine ].

Return to the Secrets Engines page and select [ Enable Engine ].

Select KV from the list, and then select [ Next ].

Enter kv-seal-wrapped in the path field, expand Method Options, select the Seal Wrap checkbox, and select [ Enable Engine ].

Select Method Options to expand and select the Seal Wrap checkbox.

Test the Seal Wrap feature

To test the Seal Wrap feature, perform the following tasks:

Test the feature
View the encrypted secrets

Test the feature

To test the Seal Wrap feature, choose the appropriate method and follow the instructions:

Use the CLI command

Perform the following steps to use the CLI command method to enable Seal Wrap:

Write a secret at kv-unwrapped/unwrapped for testing.

Shell

vault kv put kv-unwrapped/unwrapped password="my-long-password"

Read the path to verify.

Shell

vault kv get kv-unwrapped/unwrapped

====== Data ======
Key         Value
---         -----
password    my-long-password

Write the same secret at kv-seal-wrapped/wrapped for testing.

Shell

vault kv put kv-seal-wrapped/wrapped password="my-long-password"

Read the path to verify.

Shell

vault kv get kv-seal-wrapped/wrapped

====== Data ======
Key         Value
---         -----
password    my-long-password

Using a valid token, you can write and read secrets the same way, regardless of the seal wrap.

Use the Web UI

Perform the following steps to use the Web UI method to test Seal Wrap:

Select kv-unwrapped and select [ Create secret ].

Enter the following information:

In Path for this secret, enter unwrapped.
In Secret key, enter password.
In Value, enter my-longpassword.

Select [ Save ].

Repeat the same step for kv-seal-wrapped to write the same secret at the kv-seal-wrapped/wrapped path.

Select [ Save ].

Using a valid token, you can write and read secrets the same way, regardless of the seal wrap

View the encrypted secrets

To view the encrypted secrets, choose the appropriate method and follow the instructions:

The following examples assume the Vault server is configured to use the local file system (/tmp/vault) as its storage backend:

None

# Configure the storage backend for Vault
storage "file" {
  path = "/tmp/vault"
}

Use the CLI command

Perform the following steps to use the CLI command method to view the encrypted secrets:

SSH into the machine where the Vault server is running, and check the stored values in the /tmp/vault directory.

Shell

 cd /tmp/vault/logical

In the /tmp/vault/logical directory, there are two sub-directories. One maps to kv-unwrapped/ and another maps to kv-seal-wrapped/ although you cannot tell by the folder names.View the secret at rest. One of the directories maps to kv-unwrapped/unwrapped.Example:

Shell

cd 2da357cd-55f2-7eed-c46e-c477b70bed18

View its content. The password value is encrypted.

Shell

cat _unwrapped

{"Value":"AAAAAQICk547prhuhMiBXLq2lx8ZkMpSB3p+GKHAwuMhKrZGSeqsFevMS6YoqTVlbvpU9B4zWPZ2HA
SeNZ3YMw=="}

Another directory maps to kv-seal-wrapped/wrapped.

Shell

cd ../5bcea44d-28a3-87af-393b-c6d398fe41d8

View its content. The password value is encrypted.

Shell

cat _wrapped

{"Value":"ClBAg9oN7zBBaDBZcsilDAyGkL7soPe7vBA5+ADADuyzo8GuHZHb9UFN2nF1h0OpKEgCIkG3JNHcXt
tZqCi6szcuNBgF3pwhWGwB4FREM3b5CRIQYK7239Q92gRGrcBBeZD6ghogEtSBDmZJBahk7n4lIYF3X4iBqmwZgH
Vo4lzWur7rzncgASofCIIhENEEGghoc21fZGVtbyINaHNtX2htYWNfZGVtb3M="}

Secrets are encrypted regardless; however, the seal-wrapped value is significantly longer despite the fact that both values are the same, my-long-password.

Use the Web UI

Perform the following steps to use the Web UI method to view the encrypted secrets:

SSH into the machine where the Vault server is running, and check the stored values in the /tmp/vault directory.

Shell

 cd /tmp/vault/logical

Under the /tmp/vault/logical directory, there are two sub-directories. One maps to kv-unwrapped/ and another maps to kv-seal-wrapped/ although you cannot tell by the folder names.View the secret at rest. One of the directories maps to kv-unwrapped/unwrapped.Example:

Shell

cd 2da357cd-55f2-7eed-c46e-c477b70bed18

View its content. The password value is encrypted.

Shell

cat _unwrapped

{"Value":"AAAAAQICk547prhuhMiBXLq2lx8ZkMpSB3p+GKHAwuMhKrZGSeqsFevMS6YoqTVlbvpU9B4zWPZ2HA
SeNZ3YMw=="}

Another directory maps to kv-seal-wrapped/wrapped.

Shell

cd ../5bcea44d-28a3-87af-393b-c6d398fe41d8

View its content. The password value is encrypted.

Shell

cat _wrapped

{"Value":"ClBAg9oN7zBBaDBZcsilDAyGkL7soPe7vBA5+ADADuyzo8GuHZHb9UFN2nF1h0OpKEgCIkG3JNHcXt
tZqCi6szcuNBgF3pwhWGwB4FREM3b5CRIQYK7239Q92gRGrcBBeZD6ghogEtSBDmZJBahk7n4lIYF3X4iBqmwZgH
Vo4lzWur7rzncgASofCIIhENEEGghoc21fZGVtbyINaHNtX2htYWNfZGVtb3M="}

Secrets are encrypted regardless; however, the seal-wrapped value is significantly longer even though both values are the same, my-long-password.

Enable and test the Entropy Augmentation feature

To leverage the external entropy source, set the external_entropy_access parameter to true when you enable a secrets engine or auth method. This step shows how to enable an external entropy source on a transit secrets engine.

You must enable the Entropy Augmentation feature through the CLI. At this time, we do not support enabling Entropy Augmentation through the Web UI.

Execute the following command to enable the transit secrets engine with an external entropy source by using the -external-entropy-access flag.

Shell

vault secrets enable -external-entropy-access transit

List the enabled secrets engine with -detailed flag.

Shell

vault secrets list -detailed

Path          Plugin       Accessor              ...  External Entropy Access  ...
----          ------       --------              ...  -----------------------  ...
cubbyhole/    cubbyhole    cubbyhole_a4084622    ...  false                    ...
identity/     identity     identity_b5738cb7     ...  false                    ...
sys/          system       system_a8b3552e       ...  false                    ...
transit/      transit      transit_88cd3066      ...  true                     ...

Notice that the External Entropy Access is set to true for transit/.

You can start using the transit secrets engine to encrypt your sensitive data, which leverages the HSM as its external entropy source. Regardless, the user experience remains the same as before.Example:1. Create a new encryption key named: orders.

Shell

vault write -f transit/keys/orders

2. Send a base64-encoded string to be encrypted by Vault.

Shell

vault write transit/encrypt/orders plaintext=$(base64 <<< "4111 1111 1111 1111")

Key           Value
---           -----
ciphertext    vault:v1:AY3ZF2bwGfwZ9dJLSztCLdpPUHkfl/kwaQeRITvKgn74bGYyMI+n34w1CMO8aeg=

3. Now, test to verify that you can decrypt:

Shell

vault write transit/decrypt/orders \
        ciphertext="vault:v1:AY3ZF2bwGfwZ9dJLSztCLdpPUHkfl/kwaQeRITvKgn74bGYyMI+n34w1CMO8aeg="

4. Decode to get the original data:

Shell

base64 --decode <<< Y3JlZGl0LWNhcmQtbnVtYmVyCg==

credit-card-number

When the external entropy access is enabled, the connectivity to the HSM is required. If the HSM becomes unreachable for any reason, the transit secrets engine fails to generate new keys or rotate the existing keys.

Shell

Error writing data to transit/encrypt/orders: Error making API request.

URL: PUT http://127.0.0.1:8200/v1/transit/encrypt/orders
Code: 400. Errors:

* error performing token check: failed to read entry: error initializing session
for decryption: error logging in to HSM: pkcs11: 0xE0: CKR_TOKEN_NOT_PRESENT

​Download Vault

​Install Vault

​Configure Systemd

​Configure Vault settings

​Configure Vault

​Configure HSM Auto-unseal and Entropy Augmentation

​Start the Vault Server

​Start Vault

​Initialize Vault

​Access the Vault UI

​Enable and test the Seal Wrap feature

​Enable Seal Wrap

​Use the CLI command

​Use the Web UI

​Test the Seal Wrap feature

​Test the feature

​Use the CLI command

​Use the Web UI

​View the encrypted secrets

​Use the CLI command

​Use the Web UI

​Enable and test the Entropy Augmentation feature

Download Vault

Install Vault

Configure Systemd

Configure Vault settings

Configure Vault

Configure HSM Auto-unseal and Entropy Augmentation

Start the Vault Server

Start Vault

Initialize Vault

Access the Vault UI

Enable and test the Seal Wrap feature

Enable Seal Wrap

Use the CLI command

Use the Web UI

Test the Seal Wrap feature

Test the feature

Use the CLI command

Use the Web UI

View the encrypted secrets

Use the CLI command

Use the Web UI

Enable and test the Entropy Augmentation feature