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
Sample Request
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
Sample Response
List Keys
This endpoint returns a list of all existing keys.
Method | Path |
---|---|
LIST | /keymgmt/key |
Sample Request
Sample Response
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 to0
means that all versions will be enabled.deletion_allowed
(bool: false)
– Specifies if the key is allowed to be deleted.
Sample Payload
Sample Request
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
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
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
Sample Response
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 specifiedprovider
. Cannot be changed after creation. The expected value for this parameter will differ depending on the specifiedprovider
.credentials
(map<string|string>: nil)
– The credentials to use for authentication with the specifiedprovider
. 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 specifiedprovider
.
Sample Payload
Sample Request
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
Sample Response
List KMS Providers
This endpoint returns a list of all existing KMS providers.
Method | Path |
---|---|
LIST | /keymgmt/kms |
Sample Request
Sample Response
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
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:
Sample Payload
Sample Request
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
Sample Response
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
Sample Response
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