b76a56d40c
* migrates nav data format and updates docs pages * removes sidebar_title from content files
549 lines
14 KiB
Plaintext
549 lines
14 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: Key Management - Secrets Engines - HTTP API
|
||
description: 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:
|
||
|
||
- `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)
|
||
|
||
### 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 PEM encoding.
|
||
|
||
| 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-----"
|
||
},
|
||
"2": {
|
||
"creation_time": "2020-11-04T16:58:47.591718-08:00",
|
||
"public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----"
|
||
}
|
||
},
|
||
"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. For more information about each provider, refer to
|
||
the [KMS Providers](/docs/secrets/key-management#kms-providers) section. The following values
|
||
are supported:
|
||
|
||
- `azurekeyvault`
|
||
- `awskms`
|
||
|
||
### Common Parameters
|
||
|
||
There are common parameters that expect different values depending on the specified `provider`.
|
||
Please reference the API documentation for individual KMS providers to determine which values to
|
||
set for each of the parameters listed below.
|
||
|
||
- `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`.
|
||
|
||
- `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. The expected keys and values for this parameter
|
||
will differ depending on the specified `provider`.
|
||
|
||
### 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. The following values are supported:
|
||
|
||
- `encrypt`
|
||
- `decrypt`
|
||
- `sign`
|
||
- `verify`
|
||
- `wrap`
|
||
- `unwrap`
|
||
|
||
- `protection` `(string: "hsm")` – Specifies the protection of the key. The protection defines
|
||
where cryptographic operations are performed with the key in the KMS provider. The following
|
||
values are supported:
|
||
|
||
- `hsm`
|
||
- `software`
|
||
|
||
### 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",
|
||
"versions": {
|
||
"1": "c96a8956194f4632bc3837b64a1b45b1",
|
||
"2": "01ce657d33f64eb38f9432be543f3f52"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 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
|
||
```
|