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 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 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/
Unzip the downloaded package and move the vault binary to /usr/local/bin/.
Set the owner of the Vault binary.
Check that vault is available on the system path.
Verify the Vault version.
Enable autocompletion flags, subcommands, and arguments (where supported).
Enable autocompletion.
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.
Create a unique, non-privileged system user to run Vault.
Systemd uses documented sane defaults, so you need to set only non-default values in the configuration file.
Create a Vault service file at /etc/systemd/system/vault.service.
Add the following configuration to the Vault service file:
This section shows you how to perform the following tasks:
- Configure Vault
- Configure Auto-unseal and Entropy Augementation.
Vault uses documented sane defaults so you need to set only non-default values in the configuration file.
Create /etc/vault.d directory.
Create a Vault configuration file, vault.hcl.
Set the ownership of the /etc/vault.d directory.
Set the file permissions.
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 providing necessary connection information, as shown in the following example:
Example: vault.hcl
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, prefer to the Vault documentation here.
This section shows you haw to perform the following tasks:
- Start Vault
- Initialize Vault
- Access the Vault UI
Log in with the vault user.
Set the PKCS #11 PIN for log in 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.
You can also set the PKCS #11 PIN can 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 unsecure location. If set through the environment variable, Vault obfuscates the environment variable after reading it. The one caveat is that you need to re-set the VAULT_HSM_PIN environment variable if you restart the Vault.
Now, start the Vault server with the following command.
If this command is successful, you should see output similar to the following example:
Open a new terminal window and leave the terminal running where you started the Vault server.
In the new terminal, first, set the VAULT_ADDR environment variable.
Check the Vault status.
The output should be similar to the following:
Initialize Vault.
The output should be similar to the following:
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.
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 log in succeeds, you see the Vault UI homepage.
To enable and test the Seal Wrap feature, perform the tasks in this section.
To enable Seal Wrap, choose the appropriate method and perform the instructions:
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.
Enable k/v v1 with seal wrap. To do so, use the -seal-wrap flag when you enable the KV workflow.
To enable seal wrap, pass the -seal-wrap flag when you enable a secrets engine.
List the enabled secrets engines with details.
Notice that the Seal Wrap parameter value is true for kv-unwrapped/.
To test the Seal Wrap feature, perform the following tasks:
- Test the feature
- View the encrypted sectets
To test the Seal Wrap feature, choose the appropriate method and follow the instructions:
Write a secret at kv-unwrapped/unwrapped for testing.
Read the path to verify.
Write the same secret at kv-seal-wrapped/wrapped for testing.
Read the path to verify.
Using a valid token, you can write and read secrets the same way regardless of the seal wrap.
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 storgage backend:
SSH into the machine where the Vault server is running, and check the stored values in the /tmp/vault directory.
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:
View its content. The password value is encrypted.
Another directory maps to kv-seal-wrapped/wrapped.
View its content. The password value is encrypted.
Secrets are encrypted regardless; however, the seal-wrapped value is significantly longer despite the fact that both values are the same, my-long-password.
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 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 external entropy source by using the -external-entropy-access flag.
List the enabled secrets engine with -detailed flag.
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.
2. Send a base64-encoded string to be encrypted by Vault.
3. Now, test to verify that you can decrypt:
4. Decode to get the original data:
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.