» pkcs11 Seal

The PKCS11 seal configures Vault to use an HSM with PKCS11 as the seal wrapping mechanism. Vault Enterprise's HSM PKCS11 support is activated by one of the following:

  • The presence of a seal "pkcs11" block in Vault's configuration file
  • The presence of the environment variable VAULT_HSM_LIB set to the library's path as well as VAULT_HSM_TYPE set to pkcs11. If enabling via environment variable, all other required values (i.e. VAULT_HSM_SLOT) must be also supplied.

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. The list of creation attributes that Vault uses to generate the key are listed at the end of this document.

» Requirements

The following software packages are required for Vault Enterprise HSM:

  • PKCS#11 compatible HSM integration library
  • The GNU libltdl library — ensure that it is installed for the correct architecture of your servers

» pkcs11 Example

This example shows configuring HSM PKCS11 seal through the Vault configuration file by providing all the required values:

seal "pkcs11" {
  lib            = "/usr/vault/lib/libCryptoki2_64.so"
  slot           = "0"
  pin            = "AAAA-BBBB-CCCC-DDDD"
  key_label      = "vault-hsm-key"
  hmac_key_label = "vault-hsm-hmac-key"
}

» pkcs11 Parameters

These parameters apply to the seal stanza in the Vault configuration file:

  • lib (string: <required>): The path to the PKCS#11 library shared object file. May also be specified by the VAULT_HSM_LIB environment variable. Note: Depending on your HSM, this may be either a binary or a dynamic library, and its use may require other libraries depending on which system the Vault binary is currently running on (e.g.: a Linux system may require other libraries to interpret Windows .dll files).

  • slot (string: <required>): The slot number to use, specified as a string (e.g. "0"). May also be specified by the VAULT_HSM_SLOT environment variable.

  • pin (string: <required>): The PIN for login. May also be specified by the VAULT_HSM_PIN environment variable. If set via the environment variable, Vault will obfuscate the environment variable after reading it, and it will need to be re-set if Vault is restarted.

  • key_label (string: <required>): The label of the key to use. If the key does not exist and generation is enabled, this is the label that will be given to the generated key. May also be specified by the VAULT_HSM_KEY_LABEL environment variable.

  • hmac_key_label (string: <required>): The label of the key to use for HMACing. This needs to be a suitable type; a good choice is an AES key marked as valid for signing and verifying. If the key does not exist and generation is enabled, this is the label that will be given to the generated key. May also be specified by the VAULT_HSM_HMAC_KEY_LABEL environment variable.

  • mechanism (string: "0x1082"): The encryption/decryption mechanism to use, specified as a decimal or hexadecimal (prefixed by 0x) string. Currently only 0x1082 (corresponding to CKM_AES_CBC from the specification) is supported. May also be specified by the VAULT_HSM_MECHANISM environment variable.

  • hmac_mechanism (string: "0x0251"): The encryption/decryption mechanism to use, specified as a decimal or hexadecimal (prefixed by 0x) string. Currently only 0x0251 (corresponding to CKM_SHA256_HMAC from the specification) is supported. May also be specified by the VAULT_HSM_HMAC_MECHANISM environment variable.

  • generate_key (string: "false"): If no existing key with the label specified by key_label can be found at Vault initialization time, instructs Vault to generate a key. This is a boolean expressed as a string (e.g. "true"). May also be specified by the VAULT_HSM_GENERATE_KEY environment variable.

  • regenerate_key (string: "false"): At Vault initialization time, force generation of a new key even if one with the given key_label already exists. This is a boolean expressed as a string (e.g. "true"). May also be specified by the VAULT_HSM_REGENERATE_KEY environment variable.

» pkcs11 Environment Variables

Alternatively, the HSM seal can be activated by providing the following environment variables:

* `VAULT_HSM_LIB`
* `VAULT_HSM_TYPE`
* `VAULT_HSM_SLOT`
* `VAULT_HSM_PIN`
* `VAULT_HSM_KEY_LABEL`
* `VAULT_HSM_HMAC_KEY_LABEL`
* `VAULT_HSM_HMAC_KEY_LABEL`
* `VAULT_HSM_MECHANISM`
* `VAULT_HSM_HMAC_MECHANISM`
* `VAULT_HSM_GENERATE_KEY`
* `VAULT_HSM_REGENERATE_KEY`

» Vault Key Generation Attributes

If Vault generates the HSM key for you, the following is the list of attributes it uses. These identifiers correspond to official PKCS#11 identifiers.