HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Vault
Vault Home

HSM PKCS11 seal configuration

Auto-unseal and seal wrapping requires Vault Enterprise

Auto-unseal and seal wrapping for PKCS11 require Vault Enterprise.

Vault Enterprise enables seal wrapping by default, which means the KMS service must be available at runtime and not just during the unseal process. Refer to the Seal wrap overview for more information.

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_SEAL_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. Vault targets version 2.2 or higher of PKCS#11. Depending on any given HSM, some functions (such as key generation) may have to be performed manually.
  • 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           = "2305843009213693953"
  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, the value of the lib parameter 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: <slot or token label required>): The slot number to use, specified as a string (e.g. "2305843009213693953"). May also be specified by the VAULT_HSM_SLOT environment variable.

    Note: Slots are typically listed as hex-decimal values in the OS setup utility but this configuration uses their decimal equivalent. For example, using the HSM command-line pkcs11-tool, a slot listed as 0x2000000000000001in hex is equal to 2305843009213693953 in decimal; these values may be listed shorter or differently as determined by the HSM in use.

  • token_label (string: <slot or token label required>): The slot token label to use. May also be specified by the VAULT_HSM_TOKEN_LABEL 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, 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.

  • default_key_label (string: ""): This is the default key label for decryption operations. Prior to 0.10.1, key labels were not stored with the ciphertext. Seal entries now track the label used in encryption operations. The default value for this field is the key_label. If key_label is rotated and this value is not set, decryption may fail. May also be specified by the VAULT_HSM_DEFAULT_KEY_LABEL environment variable. This value is ignored in new installations.

  • key_id (string: ""): The ID of the key to use. The value should be a hexadecimal string (e.g., "0x33333435363434373537"). May also be specified by the VAULT_HSM_KEY_ID environment variable.

  • hmac_key_label (string: <required>): The label of the key to use for HMACing. This needs to be a suitable type. If Vault tries to create this it will attempt to use CKK_GENERIC_SECRET_KEY. 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.

  • default_hmac_key_label (string: ""): This is the default HMAC key label for signing operations. Prior to 0.10.1, HMAC key labels were not stored with the signature. Seal entries now track the label used in signing operations. The default value for this field is the hmac_key_label. If hmac_key_label is rotated and this value is not set, signature verification may fail. May also be specified by the VAULT_HSM_HMAC_DEFAULT_KEY_LABEL environment variable. This value is ignored in new installations.

  • hmac_key_id (string: ""): The ID of the HMAC key to use. The value should be a hexadecimal string (e.g., "0x33333435363434373537"). May also be specified by the VAULT_HSM_HMAC_KEY_ID environment variable.

  • mechanism (string: <best available>): The encryption/decryption mechanism to use, specified as a decimal or hexadecimal (prefixed by 0x) string. May also be specified by the VAULT_HSM_MECHANISM environment variable. Currently supported mechanisms (in order of precedence):

    • 0x1085 CKM_AES_CBC_PAD (HMAC mechanism required)
    • 0x1082 CKM_AES_CBC (HMAC mechanism required)
    • 0x1087 CKM_AES_GCM
    • 0x0009 CKM_RSA_PKCS_OAEP
    • 0x0001 CKM_RSA_PKCS

    Warning: CKM_RSA_PKCS specifies the PKCS #1 v1.5 padding scheme, which is in considered less secure than OAEP. Where possible, use of CKM_RSA_PKCS_OAEP is recommended over CKM_RSA_PKCS.

  • 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. This value is only required for specific mechanisms.

  • 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. Vault may not be able to successfully generate keys in all circumstances, such as if proprietary vendor extensions are required to create keys of a suitable type.

    NOTE: Once the initial key creation has occurred post cluster initialization, it is advisable to disable this flag to prevent any unintended key creation in the future.

  • force_rw_session (string: "false"): Force all operations to open up a read-write session to the HSM. This is a boolean expressed as a string (e.g. "true"). May also be specified by the VAULT_HSM_FORCE_RW_SESSION environment variable. This key is mainly to work around a limitation within AWS's CloudHSM v5 pkcs11 implementation.

  • max_parallel (int: 1) - The number of concurrent requests that may be in flight to the HSM at any given time.

  • disabled (string: ""): Set this to true if Vault is migrating from an auto seal configuration. Otherwise, set to false.

Refer to the Seal Migration documentation for more information about the seal migration process.

Mechanism specific flags

  • rsa_encrypt_local (string: "false"): For HSMs that do not support encryption for RSA keys, perform encryption locally. Available for mechanisms CKM_RSA_PKCS_OAEP and CKM_RSA_PKCS. May also be specified by the VAULT_HSM_RSA_ENCRYPT_LOCAL environment variable.

  • rsa_oaep_hash (string: "sha256"): Specify the hash algorithm to use for RSA with OAEP padding. Valid values are sha1, sha224, sha256, sha384, and sha512. Available for mechanism CKM_RSA_PKCS_OAEP. May also be specified by the VAULT_HSM_RSA_OAEP_HASH environment variable.

Note: Although the configuration file allows you to pass in VAULT_HSM_PIN as part of the seal's parameters, it is strongly recommended to set this value via environment variables.

pkcs11 environment variables

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

VAULT_SEAL_TYPE
VAULT_HSM_LIB
VAULT_HSM_SLOT
VAULT_HSM_TOKEN_LABEL
VAULT_HSM_PIN
VAULT_HSM_KEY_LABEL
VAULT_HSM_DEFAULT_KEY_LABEL
VAULT_HSM_KEY_ID
VAULT_HSM_HMAC_KEY_LABEL
VAULT_HSM_HMAC_DEFAULT_KEY_LABEL
VAULT_HSM_HMAC_KEY_ID
VAULT_HSM_MECHANISM
VAULT_HSM_HMAC_MECHANISM
VAULT_HSM_GENERATE_KEY
VAULT_HSM_RSA_ENCRYPT_LOCAL
VAULT_HSM_RSA_OAEP_HASH
VAULT_HSM_FORCE_RW_SESSION

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.

AES key

RSA key

Public Key

Private Key

  • CKA_CLASS: CKO_PRIVATE_KEY (It's a private key)
  • CKA_KEY_TYPE: CKK_RSA (Key type is RSA)
  • CKA_LABEL: Set to the key label set in Vault's configuration
  • CKA_ID: Set to a random 32-bit unsigned integer
  • CKA_DECRYPT: true (Key can be used for decryption)
  • CKA_UNWRAP: true (Key can be used for unwrapping)
  • CKA_TOKEN: true (Key persists to the slot/token rather than being for one session only)
  • CKA_EXTRACTABLE: false (Key cannot be exported)

HMAC key

  • CKA_CLASS: CKO_SECRET_KEY (It's a secret key)
  • CKA_KEY_TYPE: CKK_GENERIC_SECRET_KEY (Key type is a generic secret key)
  • CKA_VALUE_LEN: 32 (Key size is 256 bits)
  • CKA_LABEL: Set to the HMAC key label set in Vault's configuration
  • CKA_ID: Set to a random 32-bit unsigned integer
  • CKA_PRIVATE: true (Key is private to this slot/token)
  • CKA_TOKEN: true (Key persists to the slot/token rather than being for one session only)
  • CKA_SENSITIVE: true (Key is a sensitive value)
  • CKA_SIGN: true (Key can be used for signing)
  • CKA_VERIFY: true (Key can be used for verifying)
  • CKA_EXTRACTABLE: false (Key cannot be exported)

Key rotation

This seal supports rotating keys by using different key labels to track key versions. To rotate the key value, generate a new key in a different key label in the HSM and update 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 and are used to decrypt older data. To disable or delete old keys, Vault needs to perform seal-rewrap so that data encrypted by the old key can be decrypted using the new key.

NOTE: Prior to version 0.10.1, key information was not tracked with the ciphertext. If rotation is desired for data that was seal wrapped prior to this version must also set default_key_label and hmac_default_key_label to allow for decryption of older values.

Tutorial

Refer to the HSM Integration - Seal Wrap tutorial to learn how to enable the Seal Wrap feature to protect your data.

Edit this page on GitHub