Configure the Futurex PKCS #11 library with Vault
The Vault Hardware Security Module (HSM) auto-unseal and Seal Wrap features require Vault Enterprise with the Governance & Policy Module.
To configure the Futurex PKCS #11 library with Vault, perform the following tasks:
- Download and install Vault.
- Configure Vault.
- Use Vault.
- Enable and test the Seal Wrap feature.
- Enable and test the Entropy Augmentation feature.
The following sections describe how to perform these tasks.
Download precompiled Vault binaries at https://releases.hashicorp.com/vault/. To download Vault Enterprise binaries, follow the instructions HashiCorp provides Vault customers.
This integration requires the Enterprise HSM binary, which is available for testing: https://releases.hashicorp.com/vault/1.7.2+ent.hsm/
Run the following command to unzip the downloaded package and then move the vault binary to /usr/local/bin:
Run the following command to set the owner of the Vault binary:
Run the following command to verify the Vault version:
The vault command features opt-in autocompletion for flags, subcommands, and arguments (where supported).
Install autocompletion using the following command:
Run the following command to enable autocompletion:
Run the following command to configure Vault to use the mlock syscall without running the process as root. This operation prevents the system from swapping memory to disk.
Run the following command to create a unique, non-privileged system user to run Vault:
To configure Vault, perform the following tasks:
- Configure systemd.
- Confire Vault settings.
- Configure HSM Auto-unseal and Entropy Augmentation
Systemd uses documented sane defaults so you need to set only non-default values in the configuration file.
Run the following command to create a Vault service file at /etc/systemd/system/vault.service:
Add the following configuration to vault.service:
Vault uses documented sane defaults so you need to set only non-default values in the configuration file.
Run the following command to create /etc/vault.d dirtectory:
Run the following command to create a Vault configuration file, vault.hcl:
Run the following command to set the ownership of the /etc/vault.d directory:
Run the following command to set the file permissions:
When you start a Vault server, it normally starts in a sealed state where you must have a quorum of existing unseal keys to unseal it. By integrating Vault with the KMES Series 3, a trusted HSM key provider can automatically unseal the Vault server.
To integrate the Vault Enterprise server with a KMES Series 3, the configuration file must define the PKCS11 seal stanza and provide the 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
The path to the PKCS #11 library on the machine where Vault Enterprise is installed.
slot
The slot number to use. Set this value to 0 because the FXPKCS11 config file sets the slot to `01 by default.
key_label
The label of the key to use.
hmac_key_label
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, Vault generates a key.
For this integration, set the generate_key parameter to true so that Vault automatically creates the encryption keys that it uses for the Seal Wrap functionality on the KMES. The values set for the key_label and hmac_key_label parameters correspond with the special key label defines that youneed to set in the <CONFIG> section of the fxpkcs11.cfg file).
To get started using Vault, perform the ffollowing tasks:
- Start the Vault server.
- Initialize Vault.
- Access the Vault UI.
Log in with the vault user.
Run the following command to set the PKCS #11 PIN for log in. Use the password of the user you created on the KMES and defined in the fxpkcs11.cfg file.
You can also set the PKCS #11 PIN in the Vault configuration file ( vault.hcl) with the pin parameter, but we do not recommend that method in a production setting. As a best practice, specify the pin with the VAULT_HSM_PIN environment variable, as shown here, to prevent password exposure if the config file is compromised or stored in an unsecure location. If you set it through the environment variable, Vault obfuscates the environment variable after reading it. One caveat: You must reset the VAULT_HSM_PIN environment variable when Vault restarts.
Run the following command to start the Vault server:
If the command succeeds, expect output similar to the following example:
Open a new terminal window for later steps and leave this terminal running where you started the Vault server.
In the new terminal, run the following command to set the VAULT_ADDR environment variable
Run the following command to check the Vault status:
The output should be similar to the following example:
Run the following command to initialize Vault:
The output should be similar to the following example:
Run the following command to set the VAULT_TOKEN environment variable value to the generated Initial Root Token value displayed in the terminal output:
To interact with Vault, you must provide a valid token.
Navigate to http://localhost:8200 in a web browser.
Copy and paste the Initial Root Token output from the Vault initialization command into the Token field, then select [ Sign in ].
If the login succeeds, the Vault UI homepage displays.
You can enable Seal Wrap by using the following methods:
- CLI command
- Web UI
Perform one these methods described in the following sections.
To compare seal-wrapped data against unwrapped data, enable key/value v1 secrets engine at two different paths: kv-unwrapped and kv-seal-wrapped.
Run the following command to enable k/v v1 without seal wrap at kv-unwrapped:
Run the following command to enable k/v v1 with seal wrap by using 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
Run the following command to list the enabled secrets engines with details:
Example output:
Notice that the Seal Wrap parameter value is true for kv-seal-wrapped/.
Open a web browser and launch the Vault UI (for example, http://127.0.0.1:8200/ui) and then log in.
Select Enable new engine.
Select KV from the list, and then select [ Next ].
Enter kv-unwrapped in the path field and select Version 1 for KV version.
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. Select Version 1 for KV version.
Select [ Method Options ] to expand, and select the check box for Seal Wrap.
Select [ Enable Engine ].
You can test Seal Wrap and view encrypted secrets by using one of the following methods:
- CLI command
- Web UI
Perform one these methods described in the following sections.
Run the following command to write a secret at kv-unwrapped/unwrapped for testing:
Run the following command to read the path to verify:
Example output:
Run the following command to write the same secret at kv-seal-wrapped/wrapped for testing:
Run the following command to read the path to verify:
Example output:
Use a valid token to write and read secrets the same way regardless of the seal wrap.
Remember that you configured the Vault server to use the local file system (/tmp/vault) as its storage backend as shown in the following example:
Perform the following steps 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:
The /tmp/vault/logical directory has 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.
Go the first directory:
Run the following command to view its content. The password value is encrypted.
Go to the other directory that maps to kv-seal-wrapped/wrapped:Run the following command to view its content. The password value is encrypted.
Secrets are encrypted regardless,but the seal-wrapped value is significantly longer despite the fact that both values are the same: my-long-password.
Select kv-unwrapped and select [ Create secret ].
Enter unwrapped in the Path for this secret field. Use password in the secret key field and my-longpassword in the value field.
Select [ Save ].
Repeat the same step for kv-seal-wrapped to write the same secret at the kv-seal-wrapped/wrapped path.
Select [ Save ].
You can write and read secrets the same way regardless of the seal wrap by using a valid token.
Remember that you configured the Vault server to use the local file system (/tmp/vault) as its storage backend, as shown in the following example:
SSH into the machine where the Vault server is running, and check the stored values in the /tmp/vault directory.
The /tmp/vault/logical directory has 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.
Go to the first directory:
Run the following command to view its content. The password value is encrypted.
Another directory maps to kv-seal-wrapped/wrapped.
Run the following command to view its content. The password value is encrypted.
Secrets are encrypted regardless, but the seal-wrapped value is significantly longer despite the fact that both values are the same: my-long-password.
To leverage an external entropy source, you must set the external_entropy_access parameter to true when you enable a secrets engine or auth method.
Perform the following steps to enable the KMES as the external entropy source on a transit secrets engine:
You must enable the Entropy Augmentation feature through the CLI because we do not support using the Web UI at this time.
Run the following command to enable transit secrets engine with external entropy source using the -external-entropy-access flag:
Run the following command to list the enabled secrets engine with -detailed flag:
Example output:
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 KMES as its external entropy source. Regardless, the user experience remains the same as before.
Run the following command to create a new encryption key named orders:
Run the following command to send a base64-encoded string for Vault to encrypt:
Run the following command to test and verify that you can decrypt the string:
Run the following command to decode to get the original data:
When you enable the external entropy access, you must set the connectivity to the KMES Series 3. If the KMES becomes unreachable for any reason, the transit secrets engine fails to generate new keys or rotate the existing keys, displaying an error similar to the following example: