»Seal Wrap / FIPS 140-2
Enterprise Only: Vault's HSM auto-unseal and Seal Wrap features are a part of Vault Enterprise.
Vault Enterprise integrates with HSM platforms to opt-in automatic unsealing. HSM integration provides three pieces of special functionality:
- Master Key Wrapping: Vault protects its master key by transiting it through the HSM for encryption rather than splitting into key shares
- Automatic Unsealing: Vault stores its encrypted master key in storage, allowing for automatic unsealing
- Seal Wrapping to provide FIPS KeyStorage-conforming functionality for Critical Security Parameters
In some large organizations, there is a fair amount of complexity in designating key officers, who might be available to unseal Vault installations as the most common pattern is to deploy Vault immutably. As such automating unseal using an HSM provides a simplified yet secure way of unsealing Vault nodes as they get deployed.
Vault pulls its encrypted master key from storage and transit it through the HSM for decryption via PKCS #11 API. Once the master key is decrypted, Vault uses the master key to decrypt the encryption key to resume with Vault operations.
»Reference Material
- HashiCorp + AWS: Integrating CloudHSM with Vault Enterprise webinar
- Seal Wrap documentation
- Vault Configuration - pkcs11 Seal
- Vault Enterprise HSM Support
- NIST SC-12: Cryptographic Key Establishment and Management
- NIST SC-13: Cryptographic Protection
»Estimated Time to Complete
10 minutes
»Challenge
The Federal Information Processing Standard (FIPS) 140-2 is a U.S. Government computer security standard used to accredit cryptography modules. If your product or service does not follow FIPS' security requirements, it may complicate your ability to operate with U.S. Government data.
Aside from doing business with U.S. government, your organization may care about FIPS which approves various cryptographic ciphers for hashing, signature, key exchange, and encryption for security.
»Solution
Integrate Vault with FIPS 140-2 certified HSM and enable the Seal Wrap feature to protect your data.
Vault encrypts secrets using 256-bit AES in GCM mode with a randomly generated nonce prior to writing them to its persistent storage. By enabling seal wrap, Vault wraps your secrets with an extra layer of encryption leveraging the HSM encryption and decryption.
»Benefits of the Seal Wrap:
- Conformance with FIPS 140-2 directives on Key Storage and Key Transport as certified by Leidos
- Supports FIPS level of security equal to HSM
- For example, if you use Level 3 hardware encryption on an HSM, Vault will be using FIPS 140-2 Level 3 cryptography
- Allows Vault to be deployed in high security GRC environments (e.g. PCI-DSS, HIPAA) where FIPS guidelines important for external audits
- Pathway for Vault's use in managing Department of Defense's (DOD) or North Atlantic Treaty Organization (NATO) military secrets
»Prerequisites
This intermediate operations guide assumes that you have:
- A supported HSM cluster to be integrated with Vault
- Vault Enterprise Premium
»Steps
This guide walks you through the following steps:
»Step 1: Configure HSM Auto-unseal
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 HSM, your Vault server can be automatically unsealed by the trusted HSM key provider.
»Task 1: Write a Vault configuration file
To integrate your Vault Enterprise server with an HSM cluster, the configuration
file must define the PKCS11 seal
stanza
providing necessary connection information.
Example: config-hsm.hcl
NOTE: For the purpose of this guide, the storage backend is set to the local file system (
/tmp/vault
) to make the verification step easy.
The example configuration defines the following in its seal
stanza:
-
lib
is set to the path to the PKCS #11 library on the virtual machine where Vault Enterprise is installed -
slot
should be set to the slot number to use -
pin
is the PKCS #11 PIN for login -
key_label
defines the label of the key you want to use -
hmac_key_label
defines the label of the key you want to use for HMACing. (NOTE: HMAC is optional and only used for mechanisms that do not support authenticated data.) -
generate_key
is set totrue
. If no existing key with the label specified bykey_label
can be found at Vault initialization time, Vault generates a key
IMPORTANT: Having Vault generate its own key is the easiest way to get up and running, but for security, Vault marks the key as non-exportable. If your HSM key backup strategy requires the key to be exportable, you should generate the key yourself. Refer to the key generation attributes.
»Task 2: Initialize your Vault Enterprise server
Start the Vault server with your Vault configuration file. For example, if your
configuration file is located at /home/ec2-user/config-hsm.hcl
, the command
would look like:
In another terminal, set the VAULT_ADDR
environment variable, and initialize your Vault server.
Example:
There is only a single master key created which is encrypted by the HSM using PKCS #11, and then placed in the storage. When Vault needs to be unsealed, it grabs the HSM encrypted master key from the storage, round trips it through the HSM to decrypt the master key.
NOTE: When Vault is initialized while using an HSM, rather than unseal keys being returned to the operator, recovery keys are returned. These are generated from an internal recovery key that is split via Shamir's Secret Sharing, similar to Vault's treatment of unseal keys when running without an HSM. Some Vault operations such as generation of a root token require these recovery keys.
Login to the Vault using the generated root token to verify.
»Task 3: Verification
Stop and restart the Vault server and then verify its status:
The Sealed
status is false
which means that the Vault was automatically
unsealed upon its start. You can proceed with Vault operations.
»Step 2: Enable Seal Wrap
NOTE: For FIPS 140-2 compliance, seal wrap requires FIPS 140-2 Certified HSM which is supported by Vault Enterprise Premium.
For some values, seal wrapping is always enabled including the recovery key, any stored key shares, the master key, the keyring, and more. When working with the key/value secret engine, you can enable seal wrap to wrap all data.
»CLI command
Check the enabled secret engines.
Notice that the seal_wrap
parameter is set to false
.
For the purpose of comparing seal wrapped data against unwrapped data, enable additional key/value secret engine at the
secret2/
path.
The above command enabled key/value version 1 with seal wrap feature enabled.
Notice that the seal_wrap
parameter is set to true
at secret2/
.
»API call using cURL
Check the enabled secret engines.
Notice that the seal_wrap
parameter is set to false
.
For the purpose of comparing seal wrapped data against unwrapped data, enable additional key/value secret engine at the
secret2/
path.
The above command enabled key/value version 1 with seal wrap feature enabled.
Notice that the seal_wrap
parameter is set to true
at secret2/
.
»Web UI
Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui
) and
then login.
For the purpose of comparing seal wrapped data against unwrapped data, enable additional key/value secret engine at the
secret2/
path.
Select Enable new engine.
- Enter
secret2
in the path field - Select Version 1 for KV version
- Select the check box for Seal Wrap
Click Enable Engine.
»Step 3: Test the Seal Wrap Feature
In this step, you are going to:
- Write some test data
- View the encrypted secrets
»CLI command
Write a secret at secret/unwrapped
.
Write the same secret at secret2/wrapped
.
Using a valid token, you can write and read secrets the same way regardless of the seal wrap.
»API call using cURL
Write a secret at secret/unwrapped
.
Write the same secret at secret2/wrapped
.
Using a valid token, you can write and read secrets the same way regardless of the seal wrap.
»Web UI
Select secret and click Create secret.
Enter the following:
- PATH FOR THIS SECTE:
unwrapped
- key:
password
- value:
my-long-password
Click Save.
Repeat the same step for secret2 to write the same secret at the
secret2/wrapped
path.
Click Save.
Using a valid token, you can write and read secrets the same way regardless of the seal wrap.
»View the encrypted secrets
Remember that the Vault server was configured to use the local file 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.
Under the /tmp/vault/sdk/logical
directory, there are two sub-directories. One
maps to secret/
and another maps to secret2/
although you cannot tell by
the folder names.
View the secret at rest.
Secrets are encrypted regardless; however, the seal-wrapped value is
significantly longer despite the fact that both values are the same,
my-long-password
.
When Vault's Seal Wrap feature is used with a FIPS 140-2 certified HSM, Vault will store Critical Security Parameters (CSPs) in a manner that is compliant with KeyStorage and KeyTransit requirements.
»Next steps
This guide used the local file system as the storage backend to keep it simple. To learn more about making your Vault cluster highly available, read the Vault HA with Consul guide.