f3df55ad58
* Adding check-legacy-links-format workflow * Adding test-link-rewrites workflow * Updating docs-content-check-legacy-links-format hash * Migrating links to new format Co-authored-by: Kendall Strautman <kendallstrautman@gmail.com>
178 lines
7.5 KiB
Plaintext
178 lines
7.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Key Management - Secrets Engines
|
|
description: >-
|
|
The Key Management secrets engine provides a consistent workflow for distribution and lifecycle
|
|
management of cryptographic keys in various key management service (KMS) providers.
|
|
---
|
|
|
|
# Key Management Secrets Engine
|
|
|
|
-> **Note**: This secrets engine requires [Vault
|
|
Enterprise](https://www.hashicorp.com/products/vault/) (1.6.0+) with the Advanced Data
|
|
Protection KMSE Module.
|
|
|
|
The Key Management secrets engine provides a consistent workflow for distribution and lifecycle
|
|
management of cryptographic keys in various key management service (KMS) providers. It allows
|
|
organizations to maintain centralized control of their keys in Vault while still taking advantage
|
|
of cryptographic capabilities native to the KMS providers.
|
|
|
|
The secrets engine generates and owns original copies of key material. When an operator decides
|
|
to distribute and manage the lifecycle of a key in one of the [supported KMS providers](#kms-providers),
|
|
a copy of the key material is distributed. This provides additional durability and disaster
|
|
recovery means for the complete lifecycle of the key in the KMS provider.
|
|
|
|
Key material will always be securely transferred in accordance with the
|
|
[key import specification](#kms-providers) of the supported KMS providers.
|
|
|
|
## Setup
|
|
|
|
Most secrets engines must be configured in advance before they can perform their
|
|
functions. These steps are usually completed by an operator or configuration
|
|
management tool.
|
|
|
|
1. Enable the Key Management secrets engine:
|
|
|
|
```text
|
|
$ vault secrets enable keymgmt
|
|
Success! Enabled the keymgmt secrets engine at: keymgmt/
|
|
```
|
|
|
|
By default, the secrets engine will mount at the name of the engine. To enable
|
|
the secrets engine at a different path, use the `-path` argument.
|
|
|
|
## Usage
|
|
|
|
After the secrets engine is mounted and a user/machine has a Vault token with
|
|
the proper permission, it can use this secrets engine to generate, distribute, and
|
|
manage the lifecycle of cryptographic keys in [supported KMS providers](#kms-providers).
|
|
|
|
1. Create a named cryptographic key of a specified type:
|
|
|
|
```text
|
|
$ vault write -f keymgmt/key/example-key type="rsa-2048"
|
|
Success! Data written to: keymgmt/key/example-key
|
|
```
|
|
|
|
Keys created by the secrets engine are considered general-purpose until
|
|
they're distributed to a KMS provider.
|
|
|
|
1. Configure a KMS provider:
|
|
|
|
```text
|
|
$ vault write keymgmt/kms/example-kms \
|
|
provider="azurekeyvault" \
|
|
key_collection="keyvault-name" \
|
|
credentials=client_id="a0454cd1-e28e-405e-bc50-7477fa8a00b7" \
|
|
credentials=client_secret="eR%HizuCVEpAKgeaUEx" \
|
|
credentials=tenant_id="cd4bf224-d114-4f96-9bbc-b8f45751c43f"
|
|
```
|
|
|
|
Conceptually, a KMS provider resource represents a destination for keys to be distributed to
|
|
and subsequently managed in. It is configured using a generic set of parameters. The values
|
|
supplied to the generic set of parameters will differ depending on the specified `provider`.
|
|
|
|
This operation creates a KMS provider that represents a named Azure Key Vault instance.
|
|
This is accomplished by specifying the `azurekeyvault` provider along with other provider-specific
|
|
parameter values. For details on how to configure each supported KMS provider, see the
|
|
[KMS Providers](#kms-providers) section.
|
|
|
|
1. Distribute a key to a KMS provider:
|
|
|
|
```text
|
|
$ vault write keymgmt/kms/example-kms/key/example-key \
|
|
purpose="encrypt,decrypt" \
|
|
protection="hsm"
|
|
```
|
|
|
|
This operation distributes a **copy** of the named key to the KMS provider with a specific
|
|
`purpose` and `protection`. The `purpose` defines the set of cryptographic capabilities
|
|
that the key will have in the KMS provider. The `protection` defines where cryptographic
|
|
operations are performed with the key in the KMS provider. See the API documentation for a list of
|
|
supported [purpose](/vault/api-docs/secret/key-management#purpose) and [protection](/vault/api-docs/secret/key-management#protection)
|
|
values.
|
|
|
|
~> **Note:** The amount of time it takes to distribute a key to a KMS provider is proportional to the
|
|
number of versions that the key has. If a timeout occurs when distributing a key to a KMS
|
|
provider, you may need to increase the [VAULT_CLIENT_TIMEOUT](/vault/docs/commands#vault_client_timeout).
|
|
|
|
1. Rotate a key:
|
|
|
|
```text
|
|
$ vault write -f keymgmt/key/example-key/rotate
|
|
```
|
|
|
|
Rotating a key creates a new key version that contains new key material. The key will be rotated
|
|
in both Vault and the KMS provider that the key has been distributed to. The new key version
|
|
will be enabled and set as the current version for cryptographic operations in the KMS provider.
|
|
|
|
1. Enable or disable key versions:
|
|
|
|
```text
|
|
$ vault write keymgmt/key/example-key min_enabled_version=2
|
|
```
|
|
|
|
The `min_enabled_version` of a key can be updated in order to enable or disable sequences of
|
|
key versions. All versions of the key less than the `min_enabled_version` will be disabled for
|
|
cryptographic operations in the KMS provider that the key has been distributed to. Setting a
|
|
`min_enabled_version` of `0` means that all key versions will be enabled.
|
|
|
|
1. Remove a key from a KMS provider:
|
|
|
|
```text
|
|
$ vault delete keymgmt/kms/example-kms/key/example-key
|
|
```
|
|
|
|
This operation results in the key being deleted from the KMS provider. The key will still exist
|
|
in the secrets engine and can be redistributed to a KMS provider at a later time.
|
|
|
|
To permanently delete the key from the secrets engine, the [delete key](/vault/api-docs/secret/key-management#delete-key)
|
|
API may be invoked.
|
|
|
|
## Key Types
|
|
|
|
The Key Management secrets engine supports generation of the following key types:
|
|
|
|
- `aes256-gcm96` - AES-GCM with a 256-bit AES key and a 96-bit nonce (symmetric)
|
|
- `rsa-2048` - RSA with bit size of 2048 (asymmetric)
|
|
- `rsa-3072` - RSA with bit size of 3072 (asymmetric)
|
|
- `rsa-4096` - RSA with bit size of 4096 (asymmetric)
|
|
- `ecdsa-p256` - ECDSA using the P-256 elliptic curve (asymmetric)
|
|
- `ecdsa-p384` - ECDSA using the P-384 elliptic curve (asymmetric)
|
|
- `ecdsa-p521` - ECDSA using the P-521 elliptic curve (asymmetric)
|
|
|
|
## KMS Providers
|
|
|
|
The Key Management secrets engine supports lifecycle management of keys in the following
|
|
KMS providers:
|
|
|
|
- [Azure Key Vault](/vault/docs/secrets/key-management/azurekeyvault)
|
|
- [AWS KMS](/vault/docs/secrets/key-management/awskms)
|
|
- [GCP Cloud KMS](/vault/docs/secrets/key-management/gcpkms)
|
|
|
|
Refer to the provider-specific documentation for details on how to properly configure each provider.
|
|
|
|
## Compatibility
|
|
|
|
The following table defines which key types are compatible with each KMS provider.
|
|
|
|
| Key Type | Azure Key Vault | AWS KMS | GCP Cloud KMS |
|
|
| -------------- | --------------- | ------- | ------------- |
|
|
| `aes256-gcm96` | No | **Yes** | **Yes** |
|
|
| `rsa-2048` | **Yes** | No | **Yes** |
|
|
| `rsa-3072` | **Yes** | No | **Yes** |
|
|
| `rsa-4096` | **Yes** | No | **Yes** |
|
|
| `ecdsa-p256` | No | No | **Yes** |
|
|
| `ecdsa-p384` | No | No | **Yes** |
|
|
| `ecdsa-p521` | No | No | No |
|
|
|
|
## Tutorial
|
|
|
|
Refer to the [Key Management Secrets Engine](/vault/tutorials/key-management) tutorial series to learn how to use the key management secrets engine for Azure and GCP.
|
|
|
|
## API
|
|
|
|
The Key Management secrets engine has a full HTTP API. Please see the
|
|
[Key Management Secrets Engine API](/vault/api-docs/secret/key-management) for more
|
|
details.
|