ec620a7765
* implement mdx remote * fix an unfenced code block * fix partials path Co-authored-by: Jim Kalafut <jkalafut@hashicorp.com>
193 lines
8.1 KiB
Plaintext
193 lines
8.1 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Key Management - Secrets Engines
|
|
sidebar_title: Key Management <sup>ENTERPRISE</sup>
|
|
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/) with the Advanced Data
|
|
Protection Module.
|
|
|
|
~> **Note:** This secrets engine is currently a **_Tech Preview_**
|
|
feature and not recommended for deployment in production.
|
|
|
|
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](/api/secret/key-management#purpose) and [protection](/api/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](https://www.vaultproject.io/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](/api/secret/key-management#delete-key)
|
|
API may be invoked.
|
|
|
|
## Key Types
|
|
|
|
The Key Management secrets engine currently supports generation of the following key types:
|
|
|
|
- `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)
|
|
|
|
## KMS Providers
|
|
|
|
The Key Management secrets engine currently supports lifecycle management of keys in the
|
|
following KMS providers.
|
|
|
|
### Azure Key Vault
|
|
|
|
The `azurekeyvault` provider represents a named [Azure Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/)
|
|
instance.
|
|
|
|
#### Authentication
|
|
|
|
The Key Management secrets engine must have sufficient permissions to manage keys in an Azure Key
|
|
Vault instance. The authentication parameters can be set in the KMS provider configuration or as
|
|
environment variables. Environment variables will take precedence. The individual parameters are
|
|
described in the [credentials](/api/secret/key-management#credentials) section of the API documentation.
|
|
|
|
If the client ID or secret are not provided and Vault is running on an Azure VM, Vault will attempt
|
|
to use [Managed Service Identity (MSI)](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/overview)
|
|
to access Azure. Note that when MSI is used, the tenant ID must still be explicitly provided by the
|
|
configuration or environment variable.
|
|
|
|
An Azure Key Vault [access policy](https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy-portal)
|
|
determines whether a given service principal, namely an application or user group, can perform certain
|
|
operations on a Key Vault instance. The service principal associated with the provided credentials must
|
|
have an access policy on the Key Vault instance with the following minimum key permissions:
|
|
|
|
- `create`
|
|
- `delete`
|
|
- `get`
|
|
- `import`
|
|
- `update`
|
|
|
|
#### Key Transfer Specification
|
|
|
|
Keys are securely transferred from the secrets engine to Azure key vault instances in accordance
|
|
with the [Azure Bring Your Own Key](https://docs.microsoft.com/en-us/azure/key-vault/keys/byok-specification)
|
|
specification.
|
|
|
|
## Learn
|
|
|
|
Refer to the [Key Management Secrets Engine](https://learn.hashicorp.com/tutorials/vault/key-management-secrets) guide for
|
|
a step-by-step tutorial.
|
|
|
|
## API
|
|
|
|
The Key Management secrets engine has a full HTTP API. Please see the
|
|
[Key Management Secrets Engine API](/api/secret/key-management) for more
|
|
details.
|