Skip to main content
The Vault Hardware Security Module (HSM) Managed Keys feature requires Vault Enterprise with the Advanced Data Protection module.
To configure the Futurex PKCS #11 library with Vault, perform the following tasks:
  1. Download and install Vault.
  2. Configure Vault.
  3. Start the Vault server.
The following sections describe how to perform these tasks.

​
Download Vault

Follow the instructions HashiCorp provides Vault customers to download precompiled Vault binaries at https://releases.hashicorp.com/vault/. This integration requires the Vault 1.10 Enterprise HSM binary, which is available for testing: https://releases.hashicorp.com/vault/1.7.2+ent.hsm/

​
Install Vault

Perform the following steps to install Vault:
1
Run the following command to unzip the downloaded package and move the vault binary to /usr/local/bin:
Shell
unzip vault_${VAULT_VERSION}+ent.hsm_linux_amd64.zip
2
Run the following command to set the owner of the Vault binary:
Shell
sudo chown root:root vault
3
Run the following command to check that the Vault is available on the system path:
Shell
sudo mv vault /usr/local/bin/
4
Run the following command to verify the Vault version:
Shell
vault --version
5
The vault command features opt-in autocompletion for flags, subcommands, and arguments (where supported).Install autocompletion by using the following command:
Shell
vault -autocomplete-install
6
Run the following command to enable autocompletion:
Shell
complete -C /usr/local/bin/vault vault
7
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.
Shell
sudo setcap cap_ipc_lock=+ep /usr/local/bin/vault
8
Run the following command to create a unique, non-privileged system user to run Vault:
Javascript
sudo useradd --system --home /etc/vault.d --shell /bin/bash vault

​
Configure Vault

To configure Vault, perform the following tasks:
  1. Configure systemd.
  2. Configure Vault settings.
  3. Configure Managed Keys.
The following sections show you how to perform these tasks.

​
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.
1
Run the following command to create a Vault service file at /etc/systemd/system/vault.service:
Shell
sudo touch /etc/systemd/system/vault.service
2
Add the following configuration to the Vault service file:
None
[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 settings

Vault uses documented sane defaults, so you must set only non-default values in the configuration file.
1
Run the following command to create the /etc/vault.d directory:
Shell
sudo mkdir --parents /etc/vault.d
2
Run the following command to create the Vault configuration file, vault.hcl:
Shell
sudo touch /etc/vault.d/vault.hcl
3
Run the following command to set the ownership of the /etc/vault.d directory:
Shell
sudo chown --recursive vault:vault /etc/vault.d
4
Run the following command to set the required file permissions:
Shell
sudo chmod 640 /etc/vault.d/vault.hcl

​
Configure Managed Keys

The kms_library stanza of vault.hcl isolates platform-specific configuration for managed keys. It defines logical names referenced within an API configuration, keeping cluster and node-specific details separated along with deployment concerns for each. To integrate the Vault Enterprise server with an HSM for supporting the Managed Keys feature, the configuration file must define the kms_library stanza providing necessary connection information, as shown in the following example:
This guide sets the storage backend to the local file system (/tmp/vault) to make the verification step easy.
Example: vault.hcl
None
# Provide your Futurex HSM connection information
kms_library "pkcs11" {
  name="kms1"
  library = "/usr/local/bin/fxpkcs11/libfxpkcs11.so"
}

storage "file" {
  path    = "/tmp/vault"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = "true"
}

disable_mlock = true
license_path = "/usr/local/bin/License.txt"

api_addr = "http://127.0.0.1:8200"
cluster_addr = "https://127.0.0.1:8201"
ui = true
The example configuration defines the following parameters in its kms_library stanza:
You can define multiple kms_library stanzas, but the value for the name key must be a unique value across all the stanza definitions in a case-insensitive manner.
ParameterDescription
nameThe logical name referred to by a managed key
libraryThe path to the PKCS #11 library shared object file.
For the full list of configuration parameters, refer to the Vault documentation (www.vaultproject.io/docs/configuration/seal/pkcs11.html#pkcs11-parameters). To configure master keys, perform the following steps:
1
Edit vault.hcl as described in this section.
2
Save your Vault license to a file on disk. The preceding sample config file specifies this as License.txt.

​
Start the Vault server

Perform the following steps to start the Vault server:
1
Log in with the vault user.
2
Run the following command to start the Vault server:
Shell
vault server -config=/etc/vault.d/vault.hcl
If the command succeeds, expect output similar to the following example:
Shell
==> Vault server configuration:

             Api Address: http://127.0.0.1:8200
                     Cgo: enabled
         Cluster Address: https://127.0.0.1:8201
              Go Version: go1.17.7
              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.10.0+ent.hsm
             Version Sha: d71d7710888891761ce43ec4e5f9d9fdeff31d8e

==> Vault server started! Log data will stream in below:
3
Open a new terminal window and leave the terminal running where the Vault server was started.