Adds documentation for GCP Cloud KMS support in key management secret…

…s engine (#13153)
hashicorp · Nov 16, 2021 · b580c62 · b580c62
1 parent b8b0ad1
commit b580c62
Show file tree

Hide file tree

Showing 8 changed files with 166 additions and 9 deletions.
diff --git a/website/content/api-docs/secret/key-management/gcpkms.mdx 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: <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. Must be set to `gcpckms`. Cannot be changed after creation.
+
+- `key_collection` `(string: <required>)` – 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<string|string>: 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: <required>)` - 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
@@ -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
@@ -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_name>-<unix_timestamp>`.
+
+## 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
@@ -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
@@ -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/<project-id>/locations/<location>/keyRings/<keyring>" \
+    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
@@ -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,19 +148,23 @@ 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.
 
 ## Compatibility
 
 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
@@ -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
@@ -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": [