Vault Secrets Engine for Google Cloud KMS
This is a plugin backend for HashiCorp Vault that manages Google Cloud KMS keys and provides pass-through encryption/decryption of data through KMS.
Please note: Security is taken seriously. If you believe you have found a security issue, do not open an issue. Responsibly disclose by contacting security@hashicorp.com.
Usage
The Google Cloud KMS Vault secrets engine is automatically bundled and included in Vault distributions. To activate the plugin, run:
$ vault secrets enable gcpkms
Optionally configure the backend with GCP credentials:
$ vault write gcpkms/config credentials="..."
Ask Vault to generate a new Google Cloud KMS key:
$ vault write gcpkms/keys/my-key \
key_ring=projects/my-project/locations/global/keyRings/my-keyring \
crypto_key=my-crypto-key
This will create a KMS key in Google Cloud and requests to Vault will be encrypted/decrypted with that key.
Encrypt some data:
$ vault write gcpkms/encrypt/my-key plaintext="hello world"
Decrypt the data:
$ vault write gcpkms/decrypt/my-key ciphertext="..."
Development
This plugin is automatically distributed and included with Vault. These instructions are only useful if you want to develop against the plugin.
- Modern Go (1.11+)
- Git
-
Clone the repo:
$ git clone https://github.com/hashicorp/vault-plugin-secrets-gcpkms $ cd vault-plugin-secrets-gcpkms
-
Build the binary:
$ make dev
-
Copy the compiled binary into a scratch dir:
$ cp $(which vault-plugin-secrets-gcpkms) ./bin/
-
Run Vault plugins from that directory:
$ vault server -dev -dev-plugin-dir=./bin $ vault secrets enable -path=gcpkms -plugin=vault-plugin-secrets-gcpkms plugin
Documentation
The documentation for the plugin lives in the main Vault
repository in the website/
folder. Please make any
documentation updates as separate Pull Requests against that repo.
Tests
This plugin has both unit tests and acceptance tests. To run the acceptance tests, you must:
- Have a GCP project with a service account with KMS admin privileges
- Set
GOOGLE_CLOUD_PROJECT
to the name of the project
We recommend running tests in a dedicated Google Cloud project. On a fresh project, you will need to enable the Cloud KMS API. This operation only needs to be completed once per project.
$ gcloud services enable cloudkms.googleapis.com --project $GOOGLE_CLOUD_PROJECT
After the API is enabled, it may take a few minutes to propagate. Please wait and try again.
To run the tests:
$ make test
Warning: the acceptance tests change real resources which may incur real costs. Please run acceptance tests at your own risk.
Cleanup
If a test panics or fails to cleanup, you can be left with orphaned KMS keys. While their monthly cost is minimal, this may be undesirable. As such, there a cleanup script is included. To execute this script, run:
$ export GOOGLE_CLOUD_PROJECT=my-test-project
$ go run test/cleanup/main.go
WARNING! This will delete all keys in most key rings, so do not run this against a production project!