luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

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 2020-11-10 09:28:28 -08:00 committed by GitHub
parent 1b2a198212
commit c62582e0de
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 736 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
website/data/api-navigation.js
View File

@ -38,6 +38,7 @@ export default [
},
{ category: 'gcp' },
{ category: 'gcpkms' },
{ category: 'key-management' },
{ category: 'kmip' },
{
category: 'kv',

1
website/data/docs-navigation.js
View File

@ -238,6 +238,7 @@ export default [
},
{ category: 'gcp' },
{ category: 'gcpkms' },
{ category: 'key-management' },
{ category: 'kmip' },
{
category: 'kv',

542
website/pages/api-docs/secret/key-management/index.mdx Normal file
View File

@ -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
```

192
website/pages/docs/secrets/key-management/index.mdx Normal file
View File

@ -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.