Configure the Futurex PKCS #11 Library with HashiCorp Vault

13min
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:
Download and install Vault.
Configure Vault.
Start the Vault server.
The following sections describe how to perform these tasks.
Download Vault
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 Vault 1.10 Enterprise HSM binary, which is available for testing: https://releases.hashicorp.com/vault/1.7.2+ent.hsm/﻿
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
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
sudo chown root:root vault
﻿
3
Run the following command to check that vault is available on the system path:
Shell
sudo mv vault /usr/local/bin/
sudo mv vault /usr/local/bin/
﻿
4
Run the following command to verify the Vault version:
Shell
vault --version
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
vault -autocomplete-install
﻿
6
Run the following command to enable autocompletion:
Shell
complete -C /usr/local/bin/vault vault
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
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:
JS
sudo useradd --system --home /etc/vault.d --shell /bin/bash vault
sudo useradd --system --home /etc/vault.d --shell /bin/bash vault
﻿
Configure Vault
To configure Vault, perform the following tasks:
Configure systemd.
Configure Vault settings.
Configure Managed Keys.
The following sections show you how to perform these tasks.
Configure systemd
Systemd uses documented sane defaults so you need to 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
sudo touch /etc/systemd/system/vault.service
﻿
2
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
[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 need to set only non-default values in the configuration file.
1
Run the following command to create /etc/vault.d directory:
Shell
sudo mkdir --parents /etc/vault.d
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
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
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
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
Text
# 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
# 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.
Parameter
Description
﻿
name
The logical name referred to by a managed key
﻿
library
The path to the PKCS #11 library shared object file.
﻿
For the full list of configuration parameters, refer to the Vault documentation here. 
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. In the preceding sample config file, this is specified as License.txt.
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
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", max_request_duration: "1m30s", max_request_size: "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:
==> 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", max_request_duration: "1m30s", max_request_size: "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.
﻿
﻿
﻿
﻿
Updated 11 Feb 2024
Did this page help you?
Edit the Futurex PKCS #11 configuration file
Test PKI operations