docs: adds documentation for key management secrets engine (#10353)
Co-authored-by: Clint <catsby@users.noreply.github.com> Co-authored-by: Yoko <yoko@hashicorp.com>
This commit is contained in:
Austin Gebauer
GitHub
parent
1b2a198212
commit
c62582e0de
|
|
@ -38,6 +38,7 @@ export default [
|
||||||
},
|
},
|
||||||
{ category: 'gcp' },
|
{ category: 'gcp' },
|
||||||
{ category: 'gcpkms' },
|
{ category: 'gcpkms' },
|
||||||
|
{ category: 'key-management' },
|
||||||
{ category: 'kmip' },
|
{ category: 'kmip' },
|
||||||
{
|
{
|
||||||
category: 'kv',
|
category: 'kv',
|
||||||
|
|
|
||||||
|
|
@ -238,6 +238,7 @@ export default [
|
||||||
},
|
},
|
||||||
{ category: 'gcp' },
|
{ category: 'gcp' },
|
||||||
{ category: 'gcpkms' },
|
{ category: 'gcpkms' },
|
||||||
|
{ category: 'key-management' },
|
||||||
{ category: 'kmip' },
|
{ category: 'kmip' },
|
||||||
{
|
{
|
||||||
category: 'kv',
|
category: 'kv',
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,542 @@
|
||||||
|
---
|
||||||
|
layout: api
|
||||||
|
page_title: Key Management - Secrets Engines - HTTP API
|
||||||
|
sidebar_title: Key Management <sup>ENTERPRISE</sup>
|
||||||
|
description: This is the API documentation for the Key Management secrets engine.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Key Management Secrets Engine (API)
|
||||||
|
|
||||||
|
This is the API documentation for the Key Management secrets engine. For general
|
||||||
|
information about the usage and operation of the secrets engine, please see the
|
||||||
|
[Key Management secrets engine documentation](/docs/secrets/key-management).
|
||||||
|
|
||||||
|
This documentation assumes the Key Management secrets engine is enabled at the
|
||||||
|
`/keymgmt` path in Vault. Since it is possible to enable secrets engines at any
|
||||||
|
location, please update your API calls accordingly.
|
||||||
|
|
||||||
|
## Create Key
|
||||||
|
|
||||||
|
This endpoint creates a named cryptographic key of a specified type. These parameters
|
||||||
|
set cannot be changed after key creation.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :------------------- |
|
||||||
|
| `POST` | `/keymgmt/key/:name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the key to create.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
- `type` `(string: "rsa-2048")` – Specifies the type of cryptographic key to create. The
|
||||||
|
following key types are supported:
|
||||||
|
- `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)
|
||||||
|
|
||||||
|
### Sample Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "rsa-2048"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request POST \
|
||||||
|
--data @payload.json \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/key/example-key
|
||||||
|
```
|
||||||
|
|
||||||
|
## Read Key
|
||||||
|
|
||||||
|
This endpoint returns information about a named key. The `keys` object will hold information
|
||||||
|
regarding each key version. Different information will be returned depending on the key type.
|
||||||
|
For example, an asymmetric key will return its public key in a standard format for the type.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :------------------- |
|
||||||
|
| `GET` | `/keymgmt/key/:name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the key to read.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/key/example-key
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"deletion_allowed": false,
|
||||||
|
"keys": {
|
||||||
|
"1": {
|
||||||
|
"creation_time": "2020-11-02T15:54:58.768473-08:00",
|
||||||
|
"public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----",
|
||||||
|
"type": "rsa-2048"
|
||||||
|
},
|
||||||
|
"2": {
|
||||||
|
"creation_time": "2020-11-04T16:58:47.591718-08:00",
|
||||||
|
"public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----",
|
||||||
|
"type": "rsa-2048"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"latest_version": 2,
|
||||||
|
"min_enabled_version": 1,
|
||||||
|
"name": "example-key",
|
||||||
|
"type": "rsa-2048"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## List Keys
|
||||||
|
|
||||||
|
This endpoint returns a list of all existing keys.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :------------- |
|
||||||
|
| `LIST` | `/keymgmt/key` |
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request LIST \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/key
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"keys": ["example-key"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Update Key
|
||||||
|
|
||||||
|
This endpoint updates a named key.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :------------------- |
|
||||||
|
| `PUT` | `/keymgmt/key/:name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the key to update.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
- `min_enabled_version` `(int: 0)` – Specifies the minimum enabled version of the key. All
|
||||||
|
versions of the key less than the specified version will be disabled for cryptographic
|
||||||
|
operations in the KMS provider that the key has been distributed to. Setting this value to
|
||||||
|
`0` means that all versions will be enabled.
|
||||||
|
|
||||||
|
- `deletion_allowed` `(bool: false)` – Specifies if the key is allowed to be deleted.
|
||||||
|
|
||||||
|
### Sample Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"min_enabled_version": 0,
|
||||||
|
"deletion_allowed": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request PUT \
|
||||||
|
--data @payload.json \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/key/example-key
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rotate Key
|
||||||
|
|
||||||
|
This endpoint rotates the version of a named key.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :-------------------------- |
|
||||||
|
| `PUT` | `/keymgmt/key/:name/rotate` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the key to rotate.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request PUT \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/key/example-key/rotate
|
||||||
|
```
|
||||||
|
|
||||||
|
## Delete Key
|
||||||
|
|
||||||
|
This endpoint deletes a named key. The key must be removed from all KMS providers that it's
|
||||||
|
been distributed to and have `deletion_allowed` set to `true` in order to be deleted.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :------- | :-------------------- |
|
||||||
|
| `DELETE` | `/keymgmt/key/:name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the key to delete.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request DELETE \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/key/example-key
|
||||||
|
```
|
||||||
|
|
||||||
|
## List KMS Providers of Key
|
||||||
|
|
||||||
|
This endpoint returns a list of all KMS providers that the named key has been distributed to.
|
||||||
|
Currently, a key can only be distributed to a single KMS provider.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :----------------------- |
|
||||||
|
| `LIST` | `/keymgmt/key/:name/kms` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the key.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request LIST \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/key/example-key/kms
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"keys": ["example-kms"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Create/Update KMS Provider
|
||||||
|
|
||||||
|
This endpoint creates or updates a KMS provider. If a KMS provider with the given `name`
|
||||||
|
does not exist, it will be created. If the KMS provider exists, it will be updated with
|
||||||
|
the given parameter values.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :-------------------- |
|
||||||
|
| `PUT` | `/keymgmt/kms/:name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the KMS provider to create or update.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
- `provider` `(string: <required>)` – Specifies the name of a KMS provider that's external to Vault.
|
||||||
|
Cannot be changed after creation. Currently, `azurekeyvault` is supported. For more information
|
||||||
|
about each provider, refer to the [KMS Providers](/docs/secrets/key-management#kms-providers) section.
|
||||||
|
|
||||||
|
- `key_collection` `(string: <required>)` – Refers to a location to store keys in the specified
|
||||||
|
provider. Cannot be changed after creation. The expected value for this parameter will differ
|
||||||
|
depending on the specified provider.
|
||||||
|
|
||||||
|
The following values are expected for each provider:
|
||||||
|
- `azurekeyvault`
|
||||||
|
- The name of an existing Azure Key Vault instance.
|
||||||
|
|
||||||
|
- `credentials` `(map<string|string>: nil)` – The credentials to use for authentication with
|
||||||
|
the specified provider. Supplying values for this parameter is optional, as credentials may
|
||||||
|
also be specified as environment variables. Environment variables will take precedence over
|
||||||
|
credentials provided via this parameter. The expected keys and values for this parameter
|
||||||
|
will differ depending on the specified provider.
|
||||||
|
|
||||||
|
The following keys and values are expected for each provider:
|
||||||
|
- `azurekeyvault`
|
||||||
|
- `tenant_id` `(string: <required>)` - The tenant ID for the Azure Active Directory
|
||||||
|
organization. May also be specified by the `AZURE_TENANT_ID` environment variable.
|
||||||
|
- `client_id` `(string: <required or MSI>)` - The client ID for credentials to invoke the
|
||||||
|
Azure APIs. May also be specified by the `AZURE_CLIENT_ID` environment variable.
|
||||||
|
- `client_secret` `(string: <required or MSI>)` - The client secret for credentials to invoke
|
||||||
|
the Azure APIs. May also be specified by the `AZURE_CLIENT_SECRET` environment variable.
|
||||||
|
- `environment` `(string: "AzurePublicCloud")` - The Azure Cloud environment API endpoints to
|
||||||
|
use. May also be specified by the `AZURE_ENVIRONMENT` environment variable.
|
||||||
|
|
||||||
|
### Sample Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"credentials": [
|
||||||
|
"client_id=example-client-id",
|
||||||
|
"client_secret=example-client-secret",
|
||||||
|
"tenant_id=example-tenant-id"
|
||||||
|
],
|
||||||
|
"key_collection": "example-keyvault-name",
|
||||||
|
"provider": "azurekeyvault"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request PUT \
|
||||||
|
--data @payload.json \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
|
||||||
|
```
|
||||||
|
|
||||||
|
## Read KMS Provider
|
||||||
|
|
||||||
|
This endpoint returns information about a KMS provider.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :-------------------- |
|
||||||
|
| `GET` | `/keymgmt/kms/:name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the KMS provider to read.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request GET \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"key_collection": "example-keyvault-name",
|
||||||
|
"provider": "azurekeyvault"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## List KMS Providers
|
||||||
|
|
||||||
|
This endpoint returns a list of all existing KMS providers.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :------------- |
|
||||||
|
| `LIST` | `/keymgmt/kms` |
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request LIST \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"keys": ["example-kms"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Delete KMS Provider
|
||||||
|
|
||||||
|
This endpoint deletes a KMS provider. A KMS provider cannot be deleted until all keys
|
||||||
|
that have been distributed to it are removed.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :------- | :-------------------- |
|
||||||
|
| `DELETE` | `/keymgmt/kms/:name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the KMS provider to delete.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request DELETE \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
|
||||||
|
```
|
||||||
|
|
||||||
|
## Distribute Key to KMS Provider
|
||||||
|
|
||||||
|
This endpoint distributes a named key to the KMS provider. The key will be securely delivered
|
||||||
|
(i.e., wrapped for protection in transit) following the key import specification of the KMS
|
||||||
|
provider. The parameters set cannot be changed after the key has been distributed.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :--------------------------------- |
|
||||||
|
| `PUT` | `/keymgmt/kms/:name/key/:key_name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the KMS provider to distribute the given key
|
||||||
|
to. This is provided as part of the request URL.
|
||||||
|
|
||||||
|
- `key_name` `(string: <required>)` – Specifies the name of the key to distribute to the given KMS
|
||||||
|
provider. This is provided as part of the request URL.
|
||||||
|
|
||||||
|
- `purpose` `([]string: <required>)` – Specifies the purpose of the key. The purpose defines a set
|
||||||
|
of cryptographic capabilities that the key will have in the KMS provider. A key must have at
|
||||||
|
least one of the supported purposes. Currently, `encrypt`, `decrypt`, `sign`, `verify`, `wrap`,
|
||||||
|
and `unwrap` are supported.
|
||||||
|
|
||||||
|
- `protection` `(string: "hsm")` – Specifies the protection of the key. The protection defines
|
||||||
|
where cryptographic operations are performed with the key in the KMS provider. Currently,
|
||||||
|
`software` and `hsm` are supported.
|
||||||
|
|
||||||
|
### Sample Payload
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"protection":"hsm",
|
||||||
|
"purpose":"encrypt,decrypt"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request PUT \
|
||||||
|
--data @payload.json \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
|
||||||
|
```
|
||||||
|
|
||||||
|
## Read Key in KMS Provider
|
||||||
|
|
||||||
|
This endpoint returns information about a key that's been distributed to a KMS provider.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :--------------------------------- |
|
||||||
|
| `GET` | `/keymgmt/kms/:name/key/:key_name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the KMS provider. This is provided as
|
||||||
|
part of the request URL.
|
||||||
|
|
||||||
|
- `key_name` `(string: <required>)` – Specifies the name of the key. This is provided as part
|
||||||
|
of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request GET \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"name": "example-key-<unix_timestamp>",
|
||||||
|
"protection":"hsm",
|
||||||
|
"purpose":"encrypt,decrypt"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## List Keys in KMS Provider
|
||||||
|
|
||||||
|
This endpoint returns a list of all keys that have been distributed to the given KMS
|
||||||
|
provider. Many keys can be distributed to a single KMS provider.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :----- | :----------------------- |
|
||||||
|
| `LIST` | `/keymgmt/kms/:name/key` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the KMS provider.
|
||||||
|
This is provided as part of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request LIST \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"keys": ["example-key"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Remove Key from KMS Provider
|
||||||
|
|
||||||
|
This endpoint removes a named key from the KMS provider. This will only delete the key 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](#delete-key) API must be invoked.
|
||||||
|
|
||||||
|
| Method | Path |
|
||||||
|
| :------- | :--------------------------------- |
|
||||||
|
| `DELETE` | `/keymgmt/kms/:name/key/:key_name` |
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
- `name` `(string: <required>)` – Specifies the name of the KMS provider. This is provided as
|
||||||
|
part of the request URL.
|
||||||
|
|
||||||
|
- `key_name` `(string: <required>)` – Specifies the name of the key. This is provided as part
|
||||||
|
of the request URL.
|
||||||
|
|
||||||
|
### Sample Request
|
||||||
|
|
||||||
|
```shell-session
|
||||||
|
$ curl \
|
||||||
|
--header "X-Vault-Token: ..." \
|
||||||
|
--request DELETE \
|
||||||
|
http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,192 @@
|
||||||
|
---
|
||||||
|
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.
|
||||||
Loading…
Reference in New Issue