awskms

package module
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 21, 2020 License: MPL-2.0 Imports: 36 Imported by: 0

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 awskms

Optionally configure the backend with GCP credentials:

$ vault write awskms/config credentials="..."

Ask Vault to generate a new Google Cloud KMS key:

$ vault write awskms/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 awskms/encrypt/my-key plaintext="hello world"

Decrypt the data:

$ vault write awskms/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/wwanglsu/vault-plugin-secrets-awskms
    $ cd vault-plugin-secrets-awskms
    
  2. Build the binary:

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

    $ cp $(which vault-plugin-secrets-awskms) ./bin/
    
  4. Run Vault plugins from that directory:

    $ vault server -dev -dev-plugin-dir=./bin
    $ vault secrets enable -path=awskms -plugin-name=vault-plugin-secrets-awskms 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

Constants

This section is empty.

Variables

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

Functions

func Backend

func Backend() *backend

Backend returns a configured instance of the backend.

func Factory

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.

Directories

Path Synopsis
cmd
test
cleanup
This script is used to iterate over all keys in the project and destroy them.
This script is used to iterate over all keys in the project and destroy them.
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL