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

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

$ 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-----",
        "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

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

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

Sample Request

$ 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

$ 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

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

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

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

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

Sample Request

$ 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

$ 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"
  }
}

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