Skip to main content
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:
  1. Download Vault.
  2. Install Vault.
  3. Configure Systemd.
  4. Configure Vault settings.
  5. Start the Vault server.
  6. Enable and test the Seal Wrap feature.
  7. 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:
1
Unzip the downloaded package and move the vault binary to /usr/local/bin/.
Shell
 unzip vault_${VAULT_VERSION}+ent.hsm_linux_amd64.zip
2
Set the owner of the Vault binary.
Shell
sudo chown root:root vault
3
Check that vault is available on the system path.
Shell
sudo mv vault /usr/local/bin/
4
Verify the Vault version.
Shell
vault --version
5
Enable autocompletion flags, subcommands, and arguments (where supported).
Shell
vault -autocomplete-install
6
Enable autocompletion.
Shell
complete -C /usr/local/bin/vault vault
7
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
8
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.
1
Create a Vault service file at /etc/systemd/system/vault.service.
Shell
sudo touch /etc/systemd/system/vault.service
2
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.
1
Create /etc/vault.d directory.
Shell
sudo mkdir --parents /etc/vault.d
2
Create a Vault configuration file, vault.hcl.
Shell
sudo touch /etc/vault.d/vault.hcl
3
Set the ownership of the /etc/vault.d directory.
Shell
sudo chown --recursive vault:vault /etc/vault.d
4
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:
ParameterDescription
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_labelDefines 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:
1
Log in with the vault user.
2
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.
3
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:
4
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:
1
In the new terminal, first, set the VAULT_ADDR environment variable.
Shell
export VAULT_ADDR='http://0.0.0.0:8200'
2
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
3
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.
4
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:
1
Go to http://localhost:8200 in a web browser.
2
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:
1
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.
2
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:
1
Open a web browser and launch the Vault UI (for example, http://127.0.0.1:8200/ui) and then log in.
2
Select Secrets engines in the left menu.
3
Select [ Enable new engine ].
4
Select KV from the list and then select [ Next ].
5
Enter kv-unwrapped in the path field and select [ Enable new engine ].
6
Return to the Secrets Engines page and select [ Enable Engine ].
7
Select KV from the list, and then select [ Next ].
8
Enter kv-seal-wrapped in the path field, expand Method Options, select the Seal Wrap checkbox, and select [ Enable Engine ].
9
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:
1
Write a secret at kv-unwrapped/unwrapped for testing.
Shell
vault kv put kv-unwrapped/unwrapped password="my-long-password"
2
Read the path to verify.
Shell
vault kv get kv-unwrapped/unwrapped

====== Data ======
Key         Value
---         -----
password    my-long-password
3
Write the same secret at kv-seal-wrapped/wrapped for testing.
Shell
vault kv put kv-seal-wrapped/wrapped password="my-long-password"
4
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:
1
Select kv-unwrapped and select [ Create secret ].
2
Enter the following information:
  • In Path for this secret, enter unwrapped.
  • In Secret key, enter password.
  • In Value, enter my-longpassword.
3
Select [ Save ].
4
Repeat the same step for kv-seal-wrapped to write the same secret at the kv-seal-wrapped/wrapped path.
5
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:
1
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
2
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
3
View its content. The password value is encrypted.
Shell
cat _unwrapped

{"Value":"AAAAAQICk547prhuhMiBXLq2lx8ZkMpSB3p+GKHAwuMhKrZGSeqsFevMS6YoqTVlbvpU9B4zWPZ2HA
SeNZ3YMw=="}
4
Another directory maps to kv-seal-wrapped/wrapped.
Shell
cd ../5bcea44d-28a3-87af-393b-c6d398fe41d8
5
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:
1
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
2
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
3
View its content. The password value is encrypted.
Shell
cat _unwrapped

{"Value":"AAAAAQICk547prhuhMiBXLq2lx8ZkMpSB3p+GKHAwuMhKrZGSeqsFevMS6YoqTVlbvpU9B4zWPZ2HA
SeNZ3YMw=="}
4
Another directory maps to kv-seal-wrapped/wrapped.
Shell
cd ../5bcea44d-28a3-87af-393b-c6d398fe41d8
5
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.
1
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
2
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/.
3
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