luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/content/docs/configuration/seal/pkcs11.mdx
Alexander Scheel 386ef0eb6b
Add clarification around vague "this" references (#13968) 
* Clarify subject of this w.r.t. TLS configuration

Thanks to @aphorise for pointing this out internally.

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify vague this in secrets/gcp docs

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify vague this in secrets/aws docs

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify vague this in secrets/database/oracle.mdx

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify vague this in seal/pkcs11 docs

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify vague this in agent/autoauth docs

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
2022-02-09 13:02:44 -05:00

274 lines
12 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: PKCS11 - Seals - Configuration
description: |-
The PKCS11 seal configures Vault to use an HSM with PKCS11 as the seal
wrapping mechanism.
---
# `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. 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](https://www.gnu.org/software/libtool/manual/html_node/Using-libltdl.html)
— 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:
```hcl
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 `0x2000000000000001`in 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.
- `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.
### 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:
```text
VAULT_HSM_LIB
VAULT_HSM_TYPE
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
- `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 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_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 configuration
- `CKA_ID`: Set to a random 32-bit unsigned integer
- `CKA_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 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.
**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.
## Learn
Refer to the [HSM Integration - Seal Wrap](https://learn.hashicorp.com/vault/operations/ops-seal-wrap)
guide for a step-by-step tutorial.
Reference in a new issue View git blame Copy permalink