gcpkms

README

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

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-name=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!

Documentation

Index

• Variables
• func Backend() *backend
• func Factory(ctx context.Context, c *logical.BackendConfig) (logical.Backend, error)
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Update(d *framework.FieldData) (bool, error)
• type Key

Variables

var (
	ErrKeyNotFound = errors.New("encryption key not found")
)

Functions

func Backend

func Backend() *backend

Backend returns a configured instance of the backend.

func Factory

func Factory(ctx context.Context, c *logical.BackendConfig) (logical.Backend, error)

Factory returns a configured instance of the backend.

Types

type Config

type Config struct {
	Credentials string   `json:"credentials"`
	Scopes      []string `json:"scopes"`
}

Config is the stored configuration.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a config with the default values.

func (*Config) Update

func (c *Config) Update(d *framework.FieldData) (bool, error)

Update updates the configuration from the given field data.

type Key

type Key struct {
	// Name is the name of the key in Vault.
	Name string `json:"name"`

	// CryptoKeyID is the full resource ID of the key on GCP.
	CryptoKeyID string `json:"crypto_key_id"`

	// MinVersion is the minimum crypto key version to allow. If left unset or set
	// to a negative number, all versions are allowed.
	MinVersion int `json:"min_version"`

	// MaxVersion is the maximum crypto key version to allow. If left unset or set
	// to a negative number, all versions are allowed.
	MaxVersion int `json:"max_version"`
}

Key represents a key from the storage backend.