pkcs11 seal
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 asVAULT_SEAL_TYPE
set topkcs11
. 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:
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 theVAULT_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 theVAULT_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 as0x2000000000000001
in hex is equal to2305843009213693953
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 theVAULT_HSM_TOKEN_LABEL
environment variable.pin
(string: <required>)
: The PIN for login. May also be specified by theVAULT_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 theVAULT_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 thekey_label
. Ifkey_label
is rotated and this value is not set, decryption may fail. May also be specified by theVAULT_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 theVAULT_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 theVAULT_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 thehmac_key_label
. Ifhmac_key_label
is rotated and this value is not set, signature verification may fail. May also be specified by theVAULT_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 theVAULT_HSM_HMAC_KEY_ID
environment variable.mechanism
(string: <best available>)
: The encryption/decryption mechanism to use, specified as a decimal or hexadecimal (prefixed by0x
) string. May also be specified by theVAULT_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 by0x
) string. Currently only0x0251
(corresponding toCKM_SHA256_HMAC
from the specification) is supported. May also be specified by theVAULT_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 bykey_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 theVAULT_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.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 theVAULT_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 totrue
if Vault is migrating from an auto seal configuration. Otherwise, set tofalse
.
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 mechanismsCKM_RSA_PKCS_OAEP
andCKM_RSA_PKCS
. May also be specified by theVAULT_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 mechanismCKM_RSA_PKCS_OAEP
. May also be specified by theVAULT_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 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
CKA_CLASS
:CKO_SECRET_KEY
(It's a secret key)CKA_KEY_TYPE
:CKK_AES
(Key type is AES)CKA_VALUE_LEN
:32
(Key size is 256 bits)CKA_LABEL
: Set to the key label set in Vault's configurationCKA_ID
: Set to a random 32-bit unsigned integerCKA_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_ENCRYPT
:true
(Key can be used for encryption)CKA_DECRYPT
:true
(Key can be used for decryption)CKA_WRAP
:true
(Key can be used for wrapping)CKA_UNWRAP
:true
(Key can be used for unwrapping)CKA_EXTRACTABLE
:false
(Key cannot be exported)
RSA key
Public Key
CKA_CLASS
:CKO_PUBLIC_KEY
(It's a public key)CKA_KEY_TYPE
:CKK_RSA
(Key type is RSA)CKA_LABEL
: Set to the key label set in Vault's configurationCKA_ID
: Set to a random 32-bit unsigned integerCKA_ENCRYPT
:true
(Key can be used for encryption)CKA_WRAP
:true
(Key can be used for wrapping)CKA_MODULUS_BITS
:2048
(Key size is 2048 bits)CKA_PUBLIC_EXPONENT
:0x10001
(Public exponent of 65537)CKA_TOKEN
:true
(Key persists to the slot/token rather than being for one session only)
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 configurationCKA_ID
: Set to a random 32-bit unsigned integerCKA_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 configurationCKA_ID
: Set to a random 32-bit unsigned integerCKA_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.
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.