mirror of
https://github.com/hashicorp/vault.git
synced 2026-05-04 20:06:27 +02:00
Adds documentation for GCP Cloud KMS support in key management secrets engine (#13153)
This commit is contained in:
Austin Gebauer
GitHub
parent
b8b0ad14ba
commit
b580c62f03
47
website/content/api-docs/secret/key-management/gcpkms.mdx
Normal file
47
website/content/api-docs/secret/key-management/gcpkms.mdx
Normal file
@ -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).
|
||||
@ -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:
|
||||
|
||||
@ -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` |
|
||||
|
||||
@ -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) |
|
||||
|
||||
73
website/content/docs/secrets/key-management/gcpkms.mdx
Normal file
73
website/content/docs/secrets/key-management/gcpkms.mdx
Normal file
@ -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` |
|
||||
@ -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
|
||||
|
||||
|
||||
@ -133,6 +133,10 @@
|
||||
{
|
||||
"title": "AWS KMS",
|
||||
"path": "secret/key-management/awskms"
|
||||
},
|
||||
{
|
||||
"title": "GCP Cloud KMS",
|
||||
"path": "secret/key-management/gcpkms"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@ -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": [
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user