From b580c62f03e13add3bc1dc38aba2ff55001f9ebd Mon Sep 17 00:00:00 2001 From: Austin Gebauer <34121980+austingebauer@users.noreply.github.com> Date: Tue, 16 Nov 2021 11:27:08 -0800 Subject: [PATCH] Adds documentation for GCP Cloud KMS support in key management secrets engine (#13153) --- .../api-docs/secret/key-management/gcpkms.mdx | 47 ++++++++++++ .../api-docs/secret/key-management/index.mdx | 6 +- .../docs/secrets/key-management/awskms.mdx | 9 +++ .../secrets/key-management/azurekeyvault.mdx | 11 +++ .../docs/secrets/key-management/gcpkms.mdx | 73 +++++++++++++++++++ .../docs/secrets/key-management/index.mdx | 19 +++-- website/data/api-docs-nav-data.json | 4 + website/data/docs-nav-data.json | 6 +- 8 files changed, 166 insertions(+), 9 deletions(-) create mode 100644 website/content/api-docs/secret/key-management/gcpkms.mdx create mode 100644 website/content/docs/secrets/key-management/gcpkms.mdx diff --git a/website/content/api-docs/secret/key-management/gcpkms.mdx b/website/content/api-docs/secret/key-management/gcpkms.mdx new file mode 100644 index 000000000000..1b493bce915e --- /dev/null +++ b/website/content/api-docs/secret/key-management/gcpkms.mdx @@ -0,0 +1,47 @@ +--- +layout: api +page_title: GCP Cloud KMS - Key Management - Secrets Engines - HTTP API +description: The GCP Cloud KMS API documentation for the Key Management secrets engine. +--- + +# GCP Cloud KMS (API) + +The Key Management secrets engine supports lifecycle management of keys in [GCP Cloud KMS](https://cloud.google.com/security-key-management) +[key rings](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings). This is accomplished by +configuring a KMS provider resource with the `gcpckms` provider and other provider-specific parameter +values. + +The following sections provide API documentation that is specific to GCP Cloud 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. Must be set to `gcpckms`. Cannot be changed after creation. + +- `key_collection` `(string: )` – Refers to the + [resource ID](https://cloud.google.com/kms/docs/resource-hierarchy#retrieve_resource_id) + of an existing GCP Cloud KMS [key ring](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings). + Cannot be changed after creation. + +- `credentials` `(map: nil)` – The credentials to use for authentication with GCP + Cloud KMS. Supplying values for this parameter is optional, as credentials may also be specified + as environment variables. See the [authentication](/docs/secrets/key-management/gcpkms#authentication) + section for details on precedence. + + - `service_account_file` `(string: )` - The path to a Google service account key file. The + key file must be readable on the host that Vault server is running on. May also be provided by the + `GOOGLE_CREDENTIALS` environment variable or by + [application default credentials](https://cloud.google.com/docs/authentication/production). diff --git a/website/content/api-docs/secret/key-management/index.mdx b/website/content/api-docs/secret/key-management/index.mdx index ddca6df4c0f8..94542584996a 100644 --- a/website/content/api-docs/secret/key-management/index.mdx +++ b/website/content/api-docs/secret/key-management/index.mdx @@ -35,6 +35,9 @@ set cannot be changed after key creation. - `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 @@ -267,6 +270,7 @@ the given parameter values. - `azurekeyvault` - `awskms` + - `gcpckms` ### Common Parameters @@ -419,8 +423,6 @@ provider. The parameters set cannot be changed after the key has been distribute - `wrap` - `unwrap` --> **Note**: AWS only supports `encrypt` and `decrypt` purposes. - - `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: diff --git a/website/content/docs/secrets/key-management/awskms.mdx b/website/content/docs/secrets/key-management/awskms.mdx index 3a3dece5ff66..c825b2e9393b 100644 --- a/website/content/docs/secrets/key-management/awskms.mdx +++ b/website/content/docs/secrets/key-management/awskms.mdx @@ -70,3 +70,12 @@ within AWS KMS. As such, key rotations performed by the secrets engine use the [manual key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-manually) process. Applications should refer to the [alias](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html) associated with imported keys. Aliases will always have the form: `hashicorp/-`. + +## Key Purpose Compatability + +The following table defines which key [purposes](/api-docs/secret/key-management#purpose) can be used +for each key type supported by AWS KMS. + +| Key Type | Purpose | +| -------------- | ----------------------- | +| `aes256-gcm96` | `encrypt` and `decrypt` | diff --git a/website/content/docs/secrets/key-management/azurekeyvault.mdx b/website/content/docs/secrets/key-management/azurekeyvault.mdx index 10f000035e94..ee2188525952 100644 --- a/website/content/docs/secrets/key-management/azurekeyvault.mdx +++ b/website/content/docs/secrets/key-management/azurekeyvault.mdx @@ -62,3 +62,14 @@ for a detailed description of individual configuration parameters. 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. + +## Key Purpose Compatability + +The following table defines which key [purposes](/api-docs/secret/key-management#purpose) can be used +for each key type supported by GCP Cloud KMS. + +| Key Type | Purpose | +| -------------- | ------------------------------------------------------- | +| `rsa-2048` | [All purposes](/api-docs/secret/key-management#purpose) | +| `rsa-3072` | [All purposes](/api-docs/secret/key-management#purpose) | +| `rsa-4096` | [All purposes](/api-docs/secret/key-management#purpose) | diff --git a/website/content/docs/secrets/key-management/gcpkms.mdx b/website/content/docs/secrets/key-management/gcpkms.mdx new file mode 100644 index 000000000000..4bff62dc0243 --- /dev/null +++ b/website/content/docs/secrets/key-management/gcpkms.mdx @@ -0,0 +1,73 @@ +--- +layout: docs +page_title: GCP Cloud KMS - Key Management - Secrets Engines +description: GCP Cloud KMS is a supported KMS provider of the Key Management secrets engine. +--- + +# GCP Cloud KMS + +The Key Management secrets engine supports lifecycle management of keys in GCP Cloud KMS +[key rings](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings). This is accomplished +by configuring a KMS provider resource with the `gcpckms` provider and other provider-specific +parameter values. + +The following sections describe how to properly configure the secrets engine to enable +the functionality. + +## Authentication + +The Key Management secrets engine must be configured with credentials that have sufficient +permissions to manage keys in an existing GCP Cloud KMS [key ring](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings). +The authentication parameters are described in the [credentials](/api/secret/key-management/gcpkms#credentials) +section of the API documentation. The authentication parameters will be set with the following order +of precedence: + +1. `GOOGLE_CREDENTIALS` environment variable +2. [KMS provider credentials](/api/secret/key-management/gcpkms#credentials) parameter +3. [Application default credentials](https://cloud.google.com/docs/authentication/production) + +The service account must be authorized with the following minimum +[IAM permissions](https://cloud.google.com/kms/docs/reference/permissions-and-roles) on the +target [key ring](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings) resource: + +- `cloudkms.cryptoKeys.create` +- `cloudkms.cryptoKeys.update` +- `cloudkms.importJobs.create` +- `cloudkms.importJobs.get` +- `cloudkms.cryptoKeyVersions.list` +- `cloudkms.cryptoKeyVersions.destroy` +- `cloudkms.cryptoKeyVersions.update` +- `cloudkms.cryptoKeyVersions.create` + +## Configuration + +The following is an example of how to configure the KMS provider resource using the Vault CLI: + +```text +$ vault write keymgmt/kms/example-kms \ + provider="gcpckms" \ + key_collection="projects//locations//keyRings/" \ + credentials=service_account_file="/path/to/service_account/credentials.json" +``` + +Refer to the GCP Cloud KMS [API documentation](/api/secret/key-management/gcpkms) +for a detailed description of individual configuration parameters. + +## Key Transfer Specification + +Keys are securely transferred from the secrets engine to GCP Cloud KMS in accordance +with the [key import](https://cloud.google.com/kms/docs/key-import) specification. + +## Key Purpose Compatability + +The following table defines which key [purposes](/api-docs/secret/key-management#purpose) can be used +for each key type supported by GCP Cloud KMS. + +| Key Type | Purpose | +| -------------- | ----------------------- | +| `aes256-gcm96` | `encrypt` and `decrypt` | +| `rsa-2048` | `decrypt` or `sign` | +| `rsa-3072` | `decrypt` or `sign` | +| `rsa-4096` | `decrypt` or `sign` | +| `ecdsa-p256` | `sign` | +| `ecdsa-p384` | `sign` | diff --git a/website/content/docs/secrets/key-management/index.mdx b/website/content/docs/secrets/key-management/index.mdx index a6e9b1914f47..850412095346 100644 --- a/website/content/docs/secrets/key-management/index.mdx +++ b/website/content/docs/secrets/key-management/index.mdx @@ -137,6 +137,9 @@ The Key Management secrets engine 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) +- `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) ## KMS Providers @@ -145,6 +148,7 @@ KMS providers: - [Azure Key Vault](/docs/secrets/key-management/azurekeyvault) - [AWS KMS](/docs/secrets/key-management/awskms) +- [GCP Cloud KMS](/docs/secrets/key-management/gcpkms) Refer to the provider-specific documentation for details on how to properly configure each provider. @@ -152,12 +156,15 @@ Refer to the provider-specific documentation for details on how to properly conf The following table defines which key types are compatible with each KMS provider. -| Key Type | Azure Key Vault | AWS KMS | -| -------------- | --------------- | ------- | -| `aes256-gcm96` | No | **Yes** | -| `rsa-2048` | **Yes** | No | -| `rsa-3072` | **Yes** | No | -| `rsa-4096` | **Yes** | No | +| Key Type | Azure Key Vault | AWS KMS | GCP Cloud KMS | +| -------------- | --------------- | ------- | ------------- | +| `aes256-gcm96` | No | **Yes** | **Yes** | +| `rsa-2048` | **Yes** | No | **Yes** | +| `rsa-3072` | **Yes** | No | **Yes** | +| `rsa-4096` | **Yes** | No | **Yes** | +| `ecdsa-p256` | No | No | **Yes** | +| `ecdsa-p384` | No | No | **Yes** | +| `ecdsa-p521` | No | No | No | ## Learn diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 0a5a0e06e230..761cdb7ef16a 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -133,6 +133,10 @@ { "title": "AWS KMS", "path": "secret/key-management/awskms" + }, + { + "title": "GCP Cloud KMS", + "path": "secret/key-management/gcpkms" } ] }, diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e4ab5e0c2697..5646b9c6007b 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1015,6 +1015,10 @@ { "title": "AWS KMS", "path": "secrets/key-management/awskms" + }, + { + "title": "GCP Cloud KMS", + "path": "secrets/key-management/gcpkms" } ] }, @@ -1271,7 +1275,7 @@ }, { "divider": true - }, + }, { "title": "Platforms", "routes": [