mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 23:21:08 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
62 lines
3.0 KiB
Plaintext
62 lines
3.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: How HSM support changes Vault behavioral
|
|
description: >-
|
|
Understand how HSM support changes the way Vault works with unseal/recovery
|
|
keys and rekey/recovery operations.
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
|
|
|
# How HSM support changes Vault behavioral
|
|
|
|
@include 'alerts/enterprise-only.mdx'
|
|
|
|
This page contains information about the behavioral differences that take
|
|
effect when using Vault with an HSM.
|
|
|
|
## Key split between unseal keys and recovery keys
|
|
|
|
Normally, Vault uses a single set of unseal keys to perform both decryption of
|
|
the cryptographic barrier and to authorize recovery operations, such as the
|
|
[`generate-root`](/vault/api-docs/system/generate-root)
|
|
functionality.
|
|
|
|
When using an HSM, because the HSM automatically unseals the barrier but
|
|
recovery operations should still have human oversight, Vault instead uses two
|
|
sets of keys: unseal keys and recovery keys.
|
|
|
|
-> **Recovery keys:** Refer to the
|
|
[Seal/Unseal](/vault/docs/concepts/seal#recovery-key) documentation to learn more
|
|
about recovery keys.
|
|
|
|
## Unseal (Root) key
|
|
|
|
Vault usually generates a root key and splits it using [Shamir's Secret
|
|
Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to prevent a
|
|
single operator from being able to modify and unseal Vault (see more
|
|
information about Vault's security model
|
|
[here](/vault/docs/internals/security)).
|
|
|
|
When using an HSM, Vault instead stores the root key, encrypted by the HSM,
|
|
into its internal storage. As a result, during an `init` command, the number of
|
|
key shares, threshold, and stored shares are required to be set to `1`, meaning
|
|
to not split the root key, so that the single key share is itself the root
|
|
key. (Vault does not do this automatically as it generally prefers to error
|
|
rather than change parameters set by an operator.)
|
|
|
|
Both rekeying the root key and rotation of the underlying data
|
|
encryption key are supported when using an HSM.
|
|
|
|
## Performance and availability
|
|
|
|
When an HSM is used for generating various Critical Security Parameters (CSPs) or for entropy augmentation,
|
|
interaction with the HSM becomes part of the request processing for
|
|
functionality using it. This means the HSM must be online and available for
|
|
those requests to succeed. Additionally, some operations are performed much
|
|
more frequently than key generation where interaction with the HSM may
|
|
impact performance. A mount with seal wrapping enabled will interact with
|
|
the HSM on every write for example. Vault tokens (non-batch) generated with
|
|
entropy augmentation enabled will interact with the HSM when created.
|