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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

MethodPath
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