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:

Download Vault.
Install Vault.
Configure systemd.
Configure Vault.
Configure HSM Auto-unseal and Entropy Augmentation.
Start using the Vault server.
Enable and test the Seal Wrap feature.
Enable and test the Entropy Augmentation feature.

Download 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/

Install Vault

Perform the following steps to install Vault:

Unzip the downloaded package and move the vault binary to /usr/local/bin/.

Shell

$ unzip vault_${VAULT_VERSION}+ent.hsm_linux_amd64.zip

Set the owner of the Vault binary.

Shell

$ sudo chown root:root vault

Check that vault is available on the system path.

Shell

$ sudo mv vault /usr/local/bin/

Verify the Vault version.

Shell

$ vault --version

The vault command features opt-in autocompletion for flags, subcommands, and arguments, where supported.

Shell

$ vault -autocomplete-install

Enable autocompletion.

Shell

$ complete -C /usr/local/bin/vault vault

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.

Shell

$ sudo setcap cap_ipc_lock=+ep /usr/local/bin/vault

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.

Create a Vault service file at /etc/systemd/system/vault.service.

Shell

$ sudo touch /etc/systemd/system/vault.service

Add the following configuration to the Vault service file:

Text

[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

Vault uses documented sane defaults, so you need to set only non-default values in the configuration file.

Create /etc/vault.d directory.

Shell

$ sudo mkdir --parents /etc/vault.d

Create a Vault configuration file, vault.hcl.

Shell

$ sudo touch /etc/vault.d/vault.hcl

Set the ownership of the /etc/vault.d directory.

Shell

$ sudo chown --recursive vault:vault /etc/vault.d

Set the file permissions.

Shell

$ sudo chmod 640 /etc/vault.d/vault.hcl

Configure HSM Auto-unseal and Entropy Augmentation

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 CryptoHub, a trusted HSM key provider can automatically unseal the Vault server. To integrate the Vault Enterprise server with a CryptoHub, the configuration file must define the PKCS11 seal stanza ( www.vaultproject.io/docs/configuration/seal/pkcs11.html) providing necessary connection information. 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 simplify the verification step.

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 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 CryptoHub. The values set for the key_label and hmac_key_label parameters correspond with the special key label defines that you must set in the <CONFIG> section of the fxpkcs11.cfg file.

For the full list of configuration parameters, refer to the Vault documentation: www.vaultproject.io/docs/configuration/seal/pkcs11.html#pkcs11-parameters.

Start using the Vault Server

Perform the following tasks to start using the Vault server:

Start the Vault server.
Initialize Vault.
Access the Vault UI.

Start the Vault server

Perform the following steps to start the Vault server:

First, log in with thevault user.

Next, set the PKCS #11 PIN for login with the following command (this is the CryptoHub identity password configured inside the <CRYPTO-OPR-PASS> tag in the fxpkcs11.cfg file).

Shell

$ export VAULT_HSM_PIN='identity_password'

You can also set the PKCS #11 PIN in the Vault configuration file (vault.hcl) with the pin parameter, but we do not recommend this in a production environment. As a best practice, 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 reset the VAULT\HSM\PIN environment variable if you restart Vault.

Now, start the Vault server with the following command.

Shell

$ vault server -config=/etc/vault.d/vault.hcl

If the command succeeded, you should see something similar to the following output:

None

==> 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:

Open a new terminal window and leave the terminal where you started the Vault server running.

Initialize Vault

Perform the following steps to initialize Vault:

In the new terminal, first, set the VAULT_ADDR environment variable.

Shell

$ export VAULT_ADDR='http://0.0.0.0:8200'

Check the Vault status.

Shell

$ vault status

The output should be similar to the following:

None

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

Initialize Vault.

Shell

$ vault operator init -recovery-shares=1 -recovery-threshold=1

The output should be similar to the following:

None

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.

Set the VAULT_TOKEN environment variable value to the generated Root Token value displayed in the terminal output.

Shell

$ export VAULT_TOKEN="s.mvX8cihrFqMWEiM9YFnlw9E1"

To interact with Vault, you must provide a valid token. Setting this environment variable allows interaction with Vault through the CLI.

Access the Vault UI

Perform the following steps to access the Vault UI:

Go tohttp://localhost:8200 in a web browser.

Copy and paste theInitial 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.

Enable and test the Seal Wrap feature

Perform the following tasks:

Enable Seal Wrap.
Test the Seal Wrap feature.

Enable Seal Wrap

Select one of the following methods to enable Seal Wrap and follow the instructions:

CLI command

To compare seal-wrapped data against unwrapped data, enable the 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.

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-seal-wrapped/.

Web UI

Open a web browser, launch the Vault UI (http://127.0.0.1:8200/ui), and then log in.

SelectEnable new engine.

SelectKV 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 and select Version 1 for KV version.

Select [ Method Options ] to expand, and select the check box for Seal Wrap.

Select [ Enable Engine ].

Test the Seal Wrap feature

Select one of the following methods to test Seal Wrap and follow the instructions:

CLI command

Perform the following steps to test the Seal Wrap feature:

Write a secret at kv-unwrapped/unwrapped for testing.

Shell

$ vault kv put kv-unwrapped/unwrapped password="my-long-password"

Read the path to verify.

Shell

$ vault kv get kv-unwrapped/unwrapped

====== Data ======
Key         Value
---         -----
password    my-long-password

Write the same secret at kv-seal-wrapped/wrapped for testing.

Shell

$ vault kv put kv-seal-wrapped/wrapped password="my-long-password"

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.

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:

None

# Configure the storage backend for Vault
storage "file" {
path = "/tmp/vault"
}

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

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:

Shell

$ cd 2da357cd-55f2-7eed-c46e-c477b70bed18

View its content. The password value is encrypted.

Shell

$ cat _unwrapped

{"Value":"AAAAAQICk547prhuhMiBXLq2lx8ZkMpSB3p+GKHAwuMhKrZGSeqsFevMS6YoqTVlbvpU9B4zWPZ2HASeNZ3YMw=="}

Another directory maps to kv-seal-wrapped/wrapped.

Shell

$ cd ../5bcea44d-28a3-87af-393b-c6d398fe41d8

View its content. The password value is encrypted.

Shell

$ cat _wrapped

{"Value":"ClBAg9oN7zBBaDBZcsilDAyGkL7soPe7vBA5+ADADuyzo8GuHZHb9UFN2nF1h0OpKEgCIkG3JNHcXttZqCi6szcuNBgF3pwhWGwB4FREM3b5CRIQYK7239Q92gRGrcBBeZD6ghogEtSBDmZJBahk7n4lIYF3X4iBqmwZgHVo4lzWur7rzncgASofCIIhENEEGghoc21fZGVtbyINaHNtX2htYWNfZGVtb3M="}

Secrets are encrypted regardless. However, the seal-wrapped value is significantly longer, even though both values are the same (my-long-password).

Web UI

Perform the following steps to test the Seal Wrap feature:

Select kv-unwrapped and click [ Create secret ].

Enter “unwrapped” in the Path for this secret field, “password” in the secret key field, and “my-long-password” in the value field.

Click [ Save ].

Repeat the same step for kv-seal-wrapped to write the same secret at the kv-seal-wrapped/wrapped path.

Click [ Save ].

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:

None

# Configure the storage backend for Vault
storage "file" {
path = "/tmp/vault"
}

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

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:

Shell

$ cd 2da357cd-55f2-7eed-c46e-c477b70bed18

View its content. The password value is encrypted.

Shell

$ cat _unwrapped

{"Value":"AAAAAQICk547prhuhMiBXLq2lx8ZkMpSB3p+GKHAwuMhKrZGSeqsFevMS6YoqTVlbvpU9B4zWPZ2HASeNZ3YMw=="}

Another directory maps to kv-seal-wrapped/wrapped.

Shell

$ cd ../5bcea44d-28a3-87af-393b-c6d398fe41d8

View its content. The password value is encrypted.

Shell

$ cat _wrapped

{"Value":"ClBAg9oN7zBBaDBZcsilDAyGkL7soPe7vBA5+ADADuyzo8GuHZHb9UFN2nF1h0OpKEgCIkG3JNHcXttZqCi6szcuNBgF3pwhWGwB4FREM3b5CRIQYK7239Q92gRGrcBBeZD6ghogEtSBDmZJBahk7n4lIYF3X4iBqmwZgHVo4lzWur7rzncgASofCIIhENEEGghoc21fZGVtbyINaHNtX2htYWNfZGVtb3M="}

Secrets are encrypted regardless. However, the seal-wrapped value is significantly longer despite both values being the same, my-long-password

Enable and test the Entropy Augmentation feature

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 CryptoHub as the external entropy source on a transit secrets engine.

The Entropy Augmentation feature must be enabled through the command-line interface (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 by using the -external-entropy-access flag.

Shell

$ vault secrets enable -external-entropy-access transit

List the enabled secrets engine with the -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/.

You can start using the transit secrets engine to encrypt your sensitive data, which leverages the CryptoHub 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, you need connectivity to the CryptoHub. If the CryptoHub 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:

None

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: CKRTOKENNOT_PRESENT

​Download Vault

​Install Vault

​Configure systemd

​Configure Vault

​Configure HSM Auto-unseal and Entropy Augmentation

​Start using the Vault Server

​Start the Vault server

​Initialize Vault

​Access the Vault UI

​Enable and test the Seal Wrap feature

​Enable Seal Wrap

​CLI command

​Web UI

​Test the Seal Wrap feature

​CLI command

​Web UI

​Enable and test the Entropy Augmentation feature

Download Vault

Install Vault

Configure systemd

Configure Vault

Configure HSM Auto-unseal and Entropy Augmentation

Start using the Vault Server

Start the Vault server

Initialize Vault

Access the Vault UI

Enable and test the Seal Wrap feature

Enable Seal Wrap

CLI command

Web UI

Test the Seal Wrap feature

CLI command

Web UI

Enable and test the Entropy Augmentation feature