Install and configure HashiCorp Vault
The Vault Hardware Security Module (HSM) auto-unseal and Seal Wrap features require Vault Enterprise with the Governance & Policy module.
Perform the following tasks to install and configure Vault:
You can download precompiled Vault binaries at https://releases.hashicorp.com/vault/. Download Vault Enterprise binaries by following the instructions available to HashiCorp Vault customers.
This integration requires the Enterprise HSM binary. You can use the following link for testing: https://releases.hashicorp.com/vault/
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.
The vault command features opt-in autocompletion for 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 memory from being swapped to disk.
Create a unique, non-privileged system user to run Vault.
Systemd uses documented sane defaults, so you must 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:
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 a Vault server is started, it normally starts in a sealed state where a quorum of existing unseal keys is required to unseal it. By integrating Vault with the , a trusted HSM key provider can automatically unseal the Vault server.
To integrate the Vault Enterprise server with a , the configuration file must define the PKCS11 seal stanza providing necessary connection information.
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:
- 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 "0" is the slot that is set by default 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 can be found at Vault initialization time, Vault generates a key.
For the full list of configuration parameters, please refer to the Vault documentation here.
First, log in with the vault user.
Next, set the PKCS #11 PIN for login with the following command (this is the identity password configured inside the <CRYPTO-OPR-PASS> tag in the fxpkcs11.cfg file).
The PKCS #11 PIN can also be set in the Vault configuration file (vault.hcl) with the pin parameter, but we do not recommend this in a production setting. The 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 stored in an unsecured location. If set through the environment variable, Vault obfuscates the environment variable after reading it. The one caveat is that you must rest the VAULT_HSM_PIN environment variable if you restart Vault.
Now, start the Vault server with the following command.
If the command succeeded, you should see something similar to the following output:
Open a new terminal window and leave the terminal where you started the Vault server running.
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 allows interaction with Vault through the CLI.
Go 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, and select [ Sign In ].
If the login succeeds, you see the Vault UI homepage.
Perform the following tasks:
Select one of the following methods to enable Seal Wrap and follow 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, 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.
List the enabled secrets engines with details.
Notice that the Seal Wrap parameter value is true for kv-seal-wrapped/.
Select one of the following methods to test Seal Wrap and follow the instructions:
Perform the following steps to test the Seal Wrap feature:
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.
Perform the following steps to view the encrypted secrets:
Remember that you configured the Vault server to use the same local file as the system (/tmp/vault) as its storage backend in this 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.
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 even though both values are the same (my-long-password).
To leverage an external entropy source, the external_entropy_access parameter must be set to true when you enable a secrets engine or auth method.
This step enables the as the external entropy source on a transit secrets engine.
The Entropy Augmentation feature must be enabled through the CLI. Currently, we do not support enabling Entropy Augmentation through the Web UI.
Execute the following command to enable transit secrets engine with external entropy source 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 as its external entropy source. Regardless, the user experience remains the same as before.
Example: Create a new encryption key named, "orders".
Send a base64-encoded string to be encrypted by Vault.
Now, test to verify that you can decrypt.
Decode to get the original data.
When the external entropy access is enabled, you need connectivity to the . If the becomes unreachable for any reason, the transit secrets engine fails to generate new keys or rotate the existing keys. The error is similar to the following example: