Google Cloud KMS secrets engine (API)
This is the API documentation for the Vault Google Cloud KMS secrets engine. For general information about the usage and operation of the Google Cloud KMS secrets engine, please see the Google Cloud KMS documentation.
This documentation assumes the Google Cloud KMS secrets engine is enabled at the
/gcpkms
path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.
Configure credentials
This endpoint configures the Google Cloud KMS secrets engine with credentials and manages the requested scope(s) for authentication.
Method | Path |
---|---|
POST | gcpkms/config |
Example policy
Parameters
credentials
(string: ""
) - The credentials to use for authenticating to Google Cloud. Leave this blank to use the Default Application Credentials or instance metadata authentication.scopes
(array<string>: []
) - The list of full-URL scopes to request when authenticating. By default, this requests https://www.googleapis.com/auth/cloudkms.
Sample payload
Sample request
Read configuration
This endpoint returns the configuration endpoint for the Google Cloud KMS secrets engine. The credentials are not returned.
Method | Path |
---|---|
GET | gcpkms/config |
Example policy
Sample request
Sample response
Delete configuration
This endpoint deletes any configuration for the Google Cloud KMS secrets engine. If there is no configuration, the endpoint still returns successfully.
Method | Path |
---|---|
DELETE | gcpkms/config |
Example policy
Sample request
Decrypt ciphertext
This endpoint uses the named encryption key to decrypt the ciphertext string. For symmetric key types, the provided ciphertext must come from a previous invocation of the /encrypt
endpoint. For asymmetric key types, the provided ciphertext must be from the encrypt operation against the corresponding key version's public key.
Method | Path |
---|---|
POST | gcpkms/decrypt/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key in Vault to use for decryption. This key must already exist in Vault and must map back to a Google Cloud KMS key. This is specified as part of the URL.additional_authenticated_data
(string: ""
) - Optional data that was specified during encryption of this payload.ciphertext
(string: ""
) - Ciphertext to decrypt as previously returned from an encrypt operation. This must be base64-encoded ciphertext as previously returned from an encrypt operation.key_version
(int: 0
) - Integer version of the crypto key version to use for decryption. This is required for asymmetric keys. For symmetric keys, Cloud KMS will choose the correct version automatically.
Sample payload
Sample request
Sample response
Encrypt plaintext
This endpoint uses the named encryption key to encrypt arbitrary plaintext string data. The response will be base64-encoded encrypted ciphertext.
Method | Path |
---|---|
POST | gcpkms/encrypt/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key in Vault to use for encryption. This key must already exist in Vault and must map back to a Google Cloud KMS key. This is specified as part of the URL.additional_authenticated_data
(string: ""
) - Optional base64-encoded data that, if specified, must also be provided to decrypt this payload.key_version
(int: 0
) - Integer version of the crypto key version to use for encryption. If unspecified, this defaults to the latest active crypto key version.plaintext
(string: ""
) - Plaintext value to be encrypted. This can be a string or binary, but the size is limited. See the Google Cloud KMS documentation for information on size limitations by key types.
Sample payload
Sample request
Sample response
Re-Encrypt existing ciphertext
This endpoint uses the named encryption key to re-encrypt the underlying cryptokey to the latest version for this ciphertext without disclosing the original plaintext value to the requestor. This is similar to "rewrapping" in Vault's transit secrets engine.
Method | Path |
---|---|
POST | gcpkms/reencrypt/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key to use for encryption. This key must already exist in Vault and Google Cloud KMS. This is specified as part of the URL.additional_authenticated_data
(string: ""
) - Optional data that, if specified, must also be provided during decryption.ciphertext
(string: ""
) - Ciphertext to be re-encrypted to the latest key version. This must be ciphertext that Vault previously generated for this named key.key_version
(int: 0
) - Integer version of the crypto key version to use for re-encryption. If unspecified, this defaults to the latest active crypto key version.
Sample payload
Sample request
Sample response
Sign digest
This endpoint uses the named encryption key to sign digest string data. The response will include the base64-encoded signature.
Method | Path |
---|---|
POST | gcpkms/sign/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key in Vault to use for signing. This key must already exist in Vault and must map back to a Google Cloud KMS key. This is specified as part of the URL.key_version
(int: <required>
) - Integer version of the crypto key version to use for signing.digest
(string: <required>
) - Digest to sign. This digest is the base64 encoded binary value, and must match the signing algorithm digest of the Cloud KMS key, for example:
Sample payload
Sample request
Sample response
Verify digest
This endpoint uses the named encryption key to verify a signature and digest string data.
Method | Path |
---|---|
POST | gcpkms/verify/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key in Vault to use for verifying. This key must already exist in Vault and must map back to a Google Cloud KMS key. This is specified as part of the URL.key_version
(int: <required>
) - Integer version of the crypto key version to use for verifying.digest
(string: <required>
) - Digest that was signed. This digest is the base64 encoded binary value, and must match the signing algorithm digest of the Cloud KMS key. For example:signature
(string: <required>
) - Signature of the digest as returned from a signing operation.
Sample payload
Sample request
Sample response
List keys
This endpoint lists the named keys available for use in Vault. It does not list all Google Cloud KMS keys.
Method | Path |
---|---|
LIST | gcpkms/keys |
Example policy
Sample request
Sample response
Create/Update Google Cloud KMS key
This endpoint is used to create or update a Google Cloud KMS key. In addition to registering the key in Vault, this endpoint will also create the corresponding Google Cloud KMS key with the given configuration options.
Method | Path |
---|---|
POST | gcpkms/keys/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key in Vault. This is specified as part of the URL.crypto_key
(string: ""
) - Name of the crypto key to use. If the given crypto key does not exist, Vault will try to create it. This defaults to the name of the key given to Vault as the parameter if unspecified.key_ring
(string: ""
) - Full Google Cloud resource ID of the key ring with the project and location (e.g. projects/my-project/locations/global/keyRings/my-keyring). If the given key ring does not exist, Vault will try to create it during a create operation.labels
(map<string>string: nil
) - Arbitrary key=value labels to apply to the crypto key. To specify multiple labels, specify this argument multiple times (e.g. labels="a=b" labels="c=d").rotation_period
(string: ""
) - Amount of time between crypto key version rotations. This is specified as a time duration value like 72h (72 hours). The smallest possible value is 24h.protection_level
(string: "software"
) - Level of protection to use for the key management. Valid values aresoftware
andhsm
. The default value issoftware
. The value cannot be changed after creation.purpose
(string: "encrypt_decrypt"
) - Purpose of the key. Valid options areasymmetric_decrypt
,asymmetric_sign
, andencrypt_decrypt
. The default value isencrypt_decrypt
. The value cannot be changed after creation.algorithm
(string: "symmetric_encryption"
) - Algorithm to use for encryption, decryption, or signing. The value depends on the key purpose. The value cannot be changed after creation. See table below for the supported algorithms of each purpose.Purpose Supported Algorithms encrypt_decrypt
symmetric_encryption
asymmetric_decrypt
rsa_decrypt_oaep_2048_sha256
rsa_decrypt_oaep_3072_sha256
rsa_decrypt_oaep_4096_sha256
asymmetric_sign
rsa_sign_pss_2048_sha256
rsa_sign_pss_3072_sha256
rsa_sign_pss_4096_sha256
rsa_sign_pkcs1_2048_sha256
rsa_sign_pkcs1_3072_sha256
rsa_sign_pkcs1_4096_sha256
ec_sign_p256_sha256
ec_sign_p384_sha384
Sample payload
Sample request
Delete Google Cloud KMS key
This endpoint deletes a key from both Vault and Google Cloud KMS. This will disable all crypto key versions for this crypto key in Google Cloud KMS and delete Vault's reference to the crypto key.
Method | Path |
---|---|
DELETE | gcpkms/keys/:key |
Example policy
Sample request
Read Google Cloud KMS key
This endpoint reads data about a Google Cloud KMS crypto key, including the key status and current primary key version.
Method | Path |
---|---|
GET | gcpkms/keys/:key |
Example policy
Sample request
Sample response
Read Vault key configuration
This endpoint reads data about a Vault's configuration of the key.
Method | Path |
---|---|
GET | gcpkms/keys/config/:key |
Example policy
Sample request
Sample response
Update Vault key configuration
This endpoint is used to update Vault's information about an existing key.
Method | Path |
---|---|
POST | gcpkms/keys/config/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key in Vault. This is specified as part of the URL.min_version
(int: 0
) - Minimum allowed crypto key version. If set to a positive value, key versions less than the given value are not permitted to be used. If set to 0 or a negative value, there is no minimum key version.max_version
(int: 0
) - Maximum allowed crypto key version. If set to a positive value, key versions greater than the given value are not permitted to be used. If set to 0 or a negative value, there is no maximum key version.
Sample payload
Sample request
Deregister crypto key
This endpoint deregisters an existing reference Vault has to a crypto key in Google Cloud KMS. The underlying Google Cloud KMS key remains unchanged.
Method | Path |
---|---|
POST | gcpkms/keys/deregister/:key |
Example policy
Sample request
Register crypto key
This endpoint registers an existing crypto key in Google Cloud KMS and makes it available for encryption and decryption in Vault.
Method | Path |
---|---|
POST | gcpkms/keys/register/:key |
Example policy
Parameters
key
(string: ""
) - Name of the key to register in Vault. This will be the named used to refer to the underlying crypto key when encrypting or decrypting data. This is specified as part of the URL.crypto_key
(string: ""
) - Full resource ID of the crypto key including the project, location, key ring, and crypto key like "projects/%s/locations/%s/keyRings/%s/cryptoKeys/%s". This crypto key must already exist in Google Cloud KMS unless verify is set to "false".verify
(bool: true
) - Verify that the given Google Cloud KMS crypto key exists and is accessible before creating the storage entry in Vault. Set this to "false" if the key will not exist at creation time.
Sample payload
Sample request
Rotate crypto key
This endpoint rotates a crypto key by creating a new crypto key version for the corresponding Google Cloud KMS key and updates the new crypto key to be the primary key for future encryptions.
It can take up to 2 hours for a new crypto key version to become the primary, so be sure to issue a read operation if you require new data to be encrypted with this key.
Method | Path |
---|---|
POST | gcpkms/keys/rotate/:key |
Example policy
Sample request
Sample response
Trim KMS key versions
This endpoint deletes old crypto key versions that are older than the key's specified min_version
.
Data encrypted with older key versions will be irrecoverable!
Method | Path |
---|---|
POST | gcpkms/keys/trim/:key |
Example policy
Sample request