open-vault/vendor/github.com/hashicorp/vault-plugin-secrets-gcpkms
2019-08-14 17:23:29 -04:00
..
.gitignore Switch to go modules (#6585) 2019-04-13 03:44:06 -04:00
.travis.yml Update vendoring 2019-04-15 14:59:52 -04:00
backend.go Update vendoring 2019-04-15 14:59:52 -04:00
config.go Update vendoring 2019-04-15 14:59:52 -04:00
go.mod Updating plugin deps 2019-08-14 17:23:29 -04:00
go.sum Updating plugin deps 2019-08-14 17:23:29 -04:00
helpers.go Update vendoring 2019-04-15 14:59:52 -04:00
key.go Create sdk/ and api/ submodules (#6583) 2019-04-12 17:54:35 -04:00
LICENSE
Makefile Update vendoring 2019-04-15 14:59:52 -04:00
path_config.go Update vendoring 2019-04-15 14:59:52 -04:00
path_decrypt.go Update vendoring 2019-04-15 14:59:52 -04:00
path_encrypt.go Update vendoring 2019-04-15 14:59:52 -04:00
path_keys.go Vendor and prep for beta 2019-06-20 23:43:02 -04:00
path_keys_config.go Update vendoring 2019-04-15 14:59:52 -04:00
path_keys_deregister.go Update vendoring 2019-04-15 14:59:52 -04:00
path_keys_register.go Update vendoring 2019-04-15 14:59:52 -04:00
path_keys_rotate.go Update vendoring 2019-04-15 14:59:52 -04:00
path_keys_trim.go Update vendoring 2019-04-15 14:59:52 -04:00
path_keys_verify.go Update vendoring 2019-04-15 14:59:52 -04:00
path_pubkey.go Update vendoring 2019-04-15 14:59:52 -04:00
path_reencrypt.go Update vendoring 2019-04-15 14:59:52 -04:00
path_sign.go Update vendoring 2019-04-15 14:59:52 -04:00
README.md

Vault Secrets Engine for Google Cloud KMS

Build Status

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
  1. Clone the repo:

    $ git clone https://github.com/hashicorp/vault-plugin-secrets-gcpkms
    $ cd vault-plugin-secrets-gcpkms
    
  2. Build the binary:

    $ make dev
    
  3. Copy the compiled binary into a scratch dir:

    $ cp $(which vault-plugin-secrets-gcpkms) ./bin/
    
  4. 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!