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.

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)
- 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)

Sample payload

{
  "type": "rsa-2048"
}

Sample request

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key

Sample response

{
  "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/key

Sample response

{
  "data": {
    "keys": ["example-key"]
  }
}

Update key

This endpoint updates a named key.

Method	Path
`POST`	`/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

{
  "min_enabled_version": 0,
  "deletion_allowed": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --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
`POST`	`/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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    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

$ 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key/kms

Sample response

{
  "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
`POST`	`/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 section. The following values are supported:

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

{
  "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms

Sample response

{
  "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/kms

Sample response

{
  "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

$ 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
`POST`	`/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:
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

{
  "protection": "hsm",
  "purpose": "encrypt,decrypt"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key

Sample response

{
  "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key

Sample response

{
  "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 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key