Your suggested change has been received. Thank you.


Suggest A Change….


HashiCorp Integrations

HashiCorp Vault


HashiCorp Vault

HashiCorp Vault

Configure your HashiCorp Vault to generate and secure an encryption key on a Luna Cloud HSM Service and use that encryption key for wrapping the HashiCorp Vault master key, providing full key life-cycle management with FIPS certified hardware and reducing the cryptographic load on the host server CPU.

We recommend you use the Luna Cloud HSM service for this integration.

HashiCorp Vault allows HSM integration as a feature and uses the HSM for:

  • Master Key Wrapping: HashiCorp vault protects its master key by transiting the master key through the HSM for encryption, instead of splitting the master key into key shares.
  • Automatic Unsealing: HashiCorp Vault stores its HSM-wrapped master key in local storage, allowing for automatic unsealing.
  • Seal Wrapping: HashiCorp Vault provides FIPS key storage conforming functionality for Critical Security Parameters.

This integration guide uses the following third party applications:

  • HashiCorp Enterprise HSM Vault Binary

This integration is supported on the following operating systems:

  • Red Hat Enterprise Linux (RHEL)


Before proceeding with the integration complete the following:

Provision Luna Cloud HSM Service

Configure the Luna Cloud HSM service for your application integration. See the section Luna Cloud HSM Service for detailed instructions on deploying and initializing a Luna Cloud HSM service partition and Luna Cloud HSM service client for your application integration.

Please take the following limitations into consideration when integrating your application with a Luna Cloud HSM service partition:

Non-FIPS algorithms: Luna Cloud HSM services operate in a FIPS and non-FIPS mode, which affects which algorithms are available on the partition. If your organization requires non-FIPS algorithms for your operations, ensure you enable the Remove FIPS restrictions check box when configuring your Luna Cloud HSM service. The FIPS mode is enabled by default.

Refer to the Supported Mechanisms in the SDK Reference Guide for more information about available FIPS and non-FIPS algorithms.

Verify Luna Cloud HSM <slot> value: LunaCM commands work on the current slot. If there is only one slot, then it is always the current slot. If you are completing an integration using Luna Cloud HSM services, you need to verify which slot on the Luna Cloud HSM service you send commands to.

If there is more than one slot, then use the slot set command to direct a command to a specified slot. You can use slot list to determine which slot numbers are in use by which Luna Cloud HSM service.

Setup HashiCorp Vault

Download and install the HashiCorp Vault and set up the system environment to support the integration. HashiCorp Vault is distributed as a binary package for all supported platforms. The HashiCorp Vault is packaged as a zip archive. For more detailed information, refer to the HashiCorp Documentation.

  1. Download the HashiCorp Vault package from HashiCorp.

  2. Unzip the package in the working directory on the host machine.

    HashiCorp Vault runs as a single binary called vault.

  3. Add the current working directory to the PATH, so that vault is executable from any directory.

  4. Verify the installation is working by opening a new terminal session and checking that the vault binary is available. Execute vault in a terminal. If the command returns Vault Help, then Vault is installed successfully.


To integrate a Luna Cloud HSM Service with HashiCorp Vault you complete the following procedures.

Enabling the PKCS#11 Seal

Enabling the PKCS#11 seal allows HashiCorp Vault to use an HSM with PKCS#11 as the seal wrapping mechanism for securing the HashiCorp Vault keys.

Create the HashiCorp Vault's configuration file, config.json, and specify the following:

# PKCS11 seal
seal "pkcs11" {
lib = "<path to cryptoki library>"
slot = "<slot number>"
pin = "<partition password>"
key_label = "HashiCorp"
hmac_key_label = "HashiCorp_hmac"
generate_key = "true"
storage "file" {
path = "/tmp/vault"

# Addresses and ports on which Vault will respond to requests
listener "tcp" {
address= ""
tls_disable = "true"
ui = true


  • lib: The path to the PKCS#11 library shared object file.
  • slot: HSM slot number.
  • pin: HSM Crypto Officer password.
  • generate_key: Instructs the vault to generate a key if no key with the label specified by key_label can be found during Vault initialization.
  • hmac_key_label: The label of the key to use for HMAC.

Alternatively, the HSM seal can be activated by providing the following environment variables: VAULT_HSM_LIB, VAULT_HSM_SLOT, VAULT_HSM_PIN, VAULT_HSM_KEY_LABEL, VAULT_HSM_HMAC_KEY_LABEL and VAULT_HSM_GENERATE_KEY. The configuration file allows you to pass in the VAULT_HSM_PIN as part of the seal's parameters, however we recommend setting this value using environment variables.

Start the vault server using the configuration file.

./vault server - config config.json

The command returns output similar to the following:

==> Vault server configuration:

    HSM PKCS#11 Version: 2.20
            HSM Library: Chrystoki
    HSM Library Version: 5.1
    HSM Manufacturer ID: Gemalto NV
               HSM Type: pkcs11
                    Cgo: enabled
           Listen 1 TCP: tcp (addr: "", cluster address: "", max_request_duration: "1m30s", max_request_size: "33554432", tls:"disabled")
              Log Level: (not set)
                  Mlock: supported: true, enabled: true
                Storage: file
                Version: Vault v0.11.4+ent.hsm
            Version Sha: cfd805d1dcffc30abfc3f93a2f957c5427fb107d

==> Vault server started! Log data will stream in below:

Initializing the HashiCorp Vault

Initialize the HashiCorp Vault to begin configuring and managing secrets.

Launch a new terminal session and export the vault address. Execute the following:

export VAULT_ADDRE=''

Check the status of the vault.

./vault status

The command returns output similar to the following:

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
HSM Enabled             false

Initialize the vault.

./vault operator init -recover-shares=1 -recovery=threshold=1

This will generate a recovery key and initial root token. Copy these values and store them in a safe place.

Note the following logs in the first terminal where Vault Server is running. Your logs will be similar to the following:

2018-11-16T06:15:48.859-0500 [INFO] core: loaded wrapping token key
2018-11-16T06:15:48.860-0500 [INFO] core: successfully mounted backend: type=kv path=secret/
2018-11-16T06:15:48.952-0500 [INFO] core: root token generated
2018-11-16T06:15:49.031-0500 [INFO] core: vault is unsealed
2018-11-16T06:15:49.032-0500 [INFO] core: post-unseal setup starting
2018-11-16T06:15:49.153-0500 [INFO] core: loaded wrapping token key
2018-11-16T06:15:49.157-0500 [INFO] core: successfully unsealed with stored key(s): stored_keys_used=1
2018-11-16T06:15:49.157-0500 [INFO] expiration: lease restore complete

Verify the keys generated on the partition by executing partition contents in lunacm.

Logging in to the HashiCorp Vault

Log in to the HashiCorp Vault to begin configuring and managing the secrets engine.

Log in to the vault.

./vault login <vault_token>

<vault_token> is the initial root token generated during vault initialization.

You will receive output similar to the following:

[root@hashicorp]# ./vault login 5tvLldtsxhKxVAGenD5abbHI
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                 Value
---                 -----
token               5tvLldtsxhKxVAGenD5abbHI
token_accessor      94w73PrwFKjk8b0MyaMmPRay
token_renewable     false
token policies      ["root"]
identity_policies   []
policies            ["root"]

If UI is enabled in configuration file (config.json), the Vault UI can be accessed at Access the URL and provide the Vault Token in the Token field to log in.

Provide the VAULT TOKEN in the Token field to login.

Using the Secrets Engine

Secrets engines are components which store, generate, or encrypt data. The kv secrets engine is used to store arbitrary secrets within the configured physical storage for vault. Key versioning can be enabled and a configurable number of versions for each key will be stored.

View the secrets.

./vault secrets list

Enable the kv engine.

./vault secrets enable version=1 kv

Write arbitrary secret data.

./vault kv put kv/my-secret my-value=s3cr3t

Display the secret value.

./vault kv get kv/my-secret

This returns data similar to the following:

====== Data ======
Key         Value
---         -----
my-value    s3cr3t

This completes the integration of HashiCorp Vault with a Luna Cloud HSM Service.

Rotating HashiCorp Vault Keys

The PKCS#11 seal supports rotating keys by using different key labels to track key versions. To rotate the key value generate a new key with a different key label in the HSM and update the vault's configuration with the new key label value. Restart your vault instance to pick up the new key label and all new encryption operations will use the updated key label.

Old keys must not be disabled or deleted as they are used to decrypt older data.

If rotation is desired for data that was seal wrapped prior to this version, set default_key_label and hmac_default_key_label to allow for decryption of older values.

If the vault server is running, stop the vault server from the terminal.

Update the config.json file as follows:

# PKCS11 seal
seal "pkcs11" {
    lib = "<path to cryptoki library>"
    slot = "<slot number>"
    pin = "<partition password>"
    key_label = "HashiCorp_rot"
    default_hmac_key_label = "HashiCorp_hmac"
    hmac_key_label = "HashiCorp_hmac_rot"
    generate_key = "true"
storage "file" {
    path = "/tmp/vault"

# Addresses and ports on which Vault will respond to requests
listener "tcp" {
    address = ""
    tls_disable = "true"

Start the vault server using the updated configuration file.

./vault server -config config.json

Launch a new terminal session and export the vault server address.

export VAULT_ADDR='\'

Verify the vault status and list the vault secrets.

./vault secrets list

This returns output similar to the following:

Path        Type        Accessor            Description
----        ----        --------            -----------
cubbyhole/  cubbyhole   cubbyhole_16b25559  per-token private secret storage
identity/   identity    identity_a6ee82e3   identity store
kv/         kv          kv_ae934885         n/a
secret/     kv          kv_70be3e30         key/value secret storage
sys/        system      system_492462c6     system endpoints used for control, policy and debugging

Verify the keys generated in the partition by executing partition contents in lunacm on the host system.

This completes the rotation of the vault keys using a Luna Cloud HSM Service.