diff --git a/website/data/api-navigation.js b/website/data/api-navigation.js index 3791b7f61..96a0065a5 100644 --- a/website/data/api-navigation.js +++ b/website/data/api-navigation.js @@ -38,6 +38,7 @@ export default [ }, { category: 'gcp' }, { category: 'gcpkms' }, + { category: 'key-management' }, { category: 'kmip' }, { category: 'kv', diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 43da866f0..69044c648 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -238,6 +238,7 @@ export default [ }, { category: 'gcp' }, { category: 'gcpkms' }, + { category: 'key-management' }, { category: 'kmip' }, { category: 'kv', diff --git a/website/pages/api-docs/secret/key-management/index.mdx b/website/pages/api-docs/secret/key-management/index.mdx new file mode 100644 index 000000000..e973c4ac4 --- /dev/null +++ b/website/pages/api-docs/secret/key-management/index.mdx @@ -0,0 +1,542 @@ +--- +layout: api +page_title: Key Management - Secrets Engines - HTTP API +sidebar_title: Key Management ENTERPRISE +description: This is 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: )` – 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 + +```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 standard format for the type. + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/keymgmt/key/:name` | + +### Parameters + +- `name` `(string: )` – 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-----", + "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 + +```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: )` – 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: )` – 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: )` – 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: )` – 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: )` – Specifies the name of the KMS provider to create or update. + This is provided as part of the request URL. + +- `provider` `(string: )` – 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](/docs/secrets/key-management#kms-providers) section. + +- `key_collection` `(string: )` – 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: 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: )` - The tenant ID for the Azure Active Directory + organization. May also be specified by the `AZURE_TENANT_ID` environment variable. + - `client_id` `(string: )` - The client ID for credentials to invoke the + Azure APIs. May also be specified by the `AZURE_CLIENT_ID` environment variable. + - `client_secret` `(string: )` - 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 + +```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: )` – 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: )` – 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: )` – 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: )` – Specifies the name of the key to distribute to the given KMS + provider. This is provided as part of the request URL. + +- `purpose` `([]string: )` – 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 + +```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: )` – Specifies the name of the KMS provider. This is provided as + part of the request URL. + +- `key_name` `(string: )` – 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-", + "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: )` – 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: )` – Specifies the name of the KMS provider. This is provided as + part of the request URL. + +- `key_name` `(string: )` – 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 +``` diff --git a/website/pages/docs/secrets/key-management/index.mdx b/website/pages/docs/secrets/key-management/index.mdx new file mode 100644 index 000000000..9f9068347 --- /dev/null +++ b/website/pages/docs/secrets/key-management/index.mdx @@ -0,0 +1,192 @@ +--- +layout: docs +page_title: Key Management - Secrets Engines +sidebar_title: Key Management ENTERPRISE +description: >- + The Key Management secrets engine provides a consistent workflow for distribution and lifecycle + management of cryptographic keys in various key management service (KMS) providers. +--- + +# Key Management Secrets Engine + +-> **Note**: This secrets engine requires [Vault +Enterprise](https://www.hashicorp.com/products/vault/) with the Advanced Data +Protection Module. + +~> **Note:** This secrets engine is currently a ***Tech Preview*** +feature and not recommended for deployment in production. + +The Key Management secrets engine provides a consistent workflow for distribution and lifecycle +management of cryptographic keys in various key management service (KMS) providers. It allows +organizations to maintain centralized control of their keys in Vault while still taking advantage +of cryptographic capabilities native to the KMS providers. + +The secrets engine generates and owns original copies of key material. When an operator decides +to distribute and manage the lifecycle of a key in one of the [supported KMS providers](#kms-providers), +a copy of the key material is distributed. This provides additional durability and disaster +recovery means for the complete lifecycle of the key in the KMS provider. + +Key material will always be securely transferred in accordance with the +[key import specification](#kms-providers) of the supported KMS providers. + +## Setup + +Most secrets engines must be configured in advance before they can perform their +functions. These steps are usually completed by an operator or configuration +management tool. + +1. Enable the Key Management secrets engine: + + ```text + $ vault secrets enable keymgmt + Success! Enabled the keymgmt secrets engine at: keymgmt/ + ``` + + By default, the secrets engine will mount at the name of the engine. To enable + the secrets engine at a different path, use the `-path` argument. + +## Usage + +After the secrets engine is mounted and a user/machine has a Vault token with +the proper permission, it can use this secrets engine to generate, distribute, and +manage the lifecycle of cryptographic keys in [supported KMS providers](#kms-providers). + +1. Create a named cryptographic key of a specified type: + + ```text + $ vault write -f keymgmt/key/example-key type="rsa-2048" + Success! Data written to: keymgmt/key/example-key + ``` + + Keys created by the secrets engine are considered general-purpose until + they're distributed to a KMS provider. + +1. Configure a KMS provider: + + ```text + $ vault write keymgmt/kms/example-kms \ + provider="azurekeyvault" \ + key_collection="keyvault-name" \ + credentials=client_id="a0454cd1-e28e-405e-bc50-7477fa8a00b7" \ + credentials=client_secret="eR%HizuCVEpAKgeaUEx" \ + credentials=tenant_id="cd4bf224-d114-4f96-9bbc-b8f45751c43f" + ``` + + Conceptually, a KMS provider resource represents a destination for keys to be distributed to + and subsequently managed in. It is configured using a generic set of parameters. The values + supplied to the generic set of parameters will differ depending on the specified `provider`. + + This operation creates a KMS provider that represents a named Azure Key Vault instance. + This is accomplished by specifying the `azurekeyvault` provider along with other provider-specific + parameter values. For details on how to configure each supported KMS provider, see the + [KMS Providers](#kms-providers) section. + +1. Distribute a key to a KMS provider: + + ```text + $ vault write keymgmt/kms/example-kms/key/example-key \ + purpose="encrypt,decrypt" \ + protection="hsm" + ``` + + This operation distributes a **copy** of the named key to the KMS provider with a specific + `purpose` and `protection`. The `purpose` defines the set of cryptographic capabilities + that the key will have in the KMS provider. The `protection` defines where cryptographic + operations are performed with the key in the KMS provider. See the API documentation for a list of + supported [purpose](/api/secret/key-management#purpose) and [protection](/api/secret/key-management#protection) + values. + + ~> **Note:** The amount of time it takes to distribute a key to a KMS provider is proportional to the + number of versions that the key has. If a timeout occurs when distributing a key to a KMS + provider, you may need to increase the [VAULT_CLIENT_TIMEOUT](https://www.vaultproject.io/docs/commands#vault_client_timeout). + +1. Rotate a key: + + ```text + $ vault write -f keymgmt/key/example-key/rotate + ``` + + Rotating a key creates a new key version that contains new key material. The key will be rotated + in both Vault and the KMS provider that the key has been distributed to. The new key version + will be enabled and set as the current version for cryptographic operations in the KMS provider. + +1. Enable or disable key versions: + + ```text + $ vault write keymgmt/key/example-key min_enabled_version=2 + ``` + + The `min_enabled_version` of a key can be updated in order to enable or disable sequences of + key versions. All versions of the key less than the `min_enabled_version` will be disabled for + cryptographic operations in the KMS provider that the key has been distributed to. Setting a + `min_enabled_version` of `0` means that all key versions will be enabled. + +1. Remove a key from a KMS provider: + + ```text + $ vault delete keymgmt/kms/example-kms/key/example-key + ``` + + This operation results in the key being deleted 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/secret/key-management#delete-key) + API may be invoked. + +## Key Types + +The Key Management secrets engine currently supports generation of the following key types: + +- `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) + +## KMS Providers + +The Key Management secrets engine currently supports lifecycle management of keys in the +following KMS providers. + +### Azure Key Vault + +The `azurekeyvault` provider represents a named [Azure Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/) +instance. + +#### Authentication + +The Key Management secrets engine must have sufficient permissions to manage keys in an Azure Key +Vault instance. The authentication parameters can be set in the KMS provider configuration or as +environment variables. Environment variables will take precedence. The individual parameters are +described in the [credentials](/api/secret/key-management#credentials) section of the API documentation. + +If the client ID or secret are not provided and Vault is running on an Azure VM, Vault will attempt +to use [Managed Service Identity (MSI)](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/overview) +to access Azure. Note that when MSI is used, the tenant ID must still be explicitly provided by the +configuration or environment variable. + +An Azure Key Vault [access policy](https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy-portal) +determines whether a given service principal, namely an application or user group, can perform certain +operations on a Key Vault instance. The service principal associated with the provided credentials must +have an access policy on the Key Vault instance with the following minimum key permissions: + +- `create` +- `delete` +- `get` +- `import` +- `update` + +#### Key Transfer Specification + +Keys are securely transferred from the secrets engine to Azure key vault instances in accordance +with the [Azure Bring Your Own Key](https://docs.microsoft.com/en-us/azure/key-vault/keys/byok-specification) +specification. + +## Learn + +Refer to the [Key Management Secrets Engine](https://learn.hashicorp.com/tutorials/vault/key-management-secrets) guide for +a step-by-step tutorial. + +## API + +The Key Management secrets engine has a full HTTP API. Please see the +[Key Management Secrets Engine API](/api/secret/key-management) for more +details.