README.md
1# Vault Secrets Engine for Google Cloud KMS
2
3[](https://travis-ci.com/hashicorp/vault-plugin-secrets-gcpkms)
4
5This is a plugin backend for [HashiCorp Vault][vault] that manages [Google Cloud
6KMS][kms] keys and provides pass-through encryption/decryption of data through
7KMS.
8
9**Please note:** Security is taken seriously. If you believe you have found a
10security issue, **do not open an issue**. Responsibly disclose by contacting
11security@hashicorp.com.
12
13
14## Usage
15
16The Google Cloud KMS Vault secrets engine is automatically bundled and included
17in [Vault][vault] distributions. To activate the plugin, run:
18
19```text
20$ vault secrets enable gcpkms
21```
22
23Optionally configure the backend with GCP credentials:
24
25```text
26$ vault write gcpkms/config credentials="..."
27```
28
29Ask Vault to generate a new Google Cloud KMS key:
30
31```text
32$ vault write gcpkms/keys/my-key \
33 key_ring=projects/my-project/locations/global/keyRings/my-keyring \
34 crypto_key=my-crypto-key
35```
36
37This will create a KMS key in Google Cloud and requests to Vault will be
38encrypted/decrypted with that key.
39
40Encrypt some data:
41
42```text
43$ vault write gcpkms/encrypt/my-key plaintext="hello world"
44```
45
46Decrypt the data:
47
48```text
49$ vault write gcpkms/decrypt/my-key ciphertext="..."
50```
51
52
53## Development
54
55This plugin is automatically distributed and included with Vault. **These
56instructions are only useful if you want to develop against the plugin.**
57
58- Modern [Go](https://golang.org) (1.11+)
59- Git
60
611. Clone the repo:
62
63 ```text
64 $ git clone https://github.com/hashicorp/vault-plugin-secrets-gcpkms
65 $ cd vault-plugin-secrets-gcpkms
66 ```
67
681. Build the binary:
69
70 ```text
71 $ make dev
72 ```
73
741. Copy the compiled binary into a scratch dir:
75
76 ```text
77 $ cp $(which vault-plugin-secrets-gcpkms) ./bin/
78 ```
79
801. Run Vault plugins from that directory:
81
82 ```text
83 $ vault server -dev -dev-plugin-dir=./bin
84 $ vault secrets enable -path=gcpkms -plugin=vault-plugin-secrets-gcpkms plugin
85 ```
86
87### Documentation
88
89The documentation for the plugin lives in the [main Vault
90repository](/hashicorp/vault) in the `website/` folder. Please make any
91documentation updates as separate Pull Requests against that repo.
92
93### Tests
94
95This plugin has both unit tests and acceptance tests. To run the acceptance
96tests, you must:
97
98- Have a GCP project with a service account with KMS admin privileges
99- Set `GOOGLE_CLOUD_PROJECT` to the name of the project
100
101We recommend running tests in a dedicated Google Cloud project. On a fresh
102project, you will need to enable the Cloud KMS API. This operation only needs to
103be completed once per project.
104
105```text
106$ gcloud services enable cloudkms.googleapis.com --project $GOOGLE_CLOUD_PROJECT
107```
108
109After the API is enabled, it may take a few minutes to propagate. Please wait
110and try again.
111
112To run the tests:
113
114```text
115$ make test
116```
117
118**Warning:** the acceptance tests change real resources which may incur real
119costs. Please run acceptance tests at your own risk.
120
121### Cleanup
122
123If a test panics or fails to cleanup, you can be left with orphaned KMS keys.
124While their monthly cost is minimal, this may be undesirable. As such, there a
125cleanup script is included. To execute this script, run:
126
127```text
128$ export GOOGLE_CLOUD_PROJECT=my-test-project
129$ go run test/cleanup/main.go
130```
131
132**WARNING!** This will delete all keys in most key rings, so do not run this
133against a production project!
134
135[kms]: https://cloud.google.com/kms
136[vault]: https://www.vaultproject.io
137
){kind=link}