gcpkms

package module

v0.24.0 Latest Latest Go to latest Published: Apr 9, 2026 License: MPL-2.0 Imports: 37 Imported by: 9

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

Clone the repo:

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

Build the binary:
```
$ make dev
```
The plugin binary will be written to the ./bin directory.

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 service account in the project with the roles "Cloud KMS Admin" and "Cloud KMS Crypto Operator"
Set GOOGLE_APPLICATION_CREDENTIALS to the service account key credentials for the above account
Set GOOGLE_CLOUD_PROJECT to the project ID
Request an increase to the Cloud Key Management Service (KMS) API Write-Requests quota to 600 per minute

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=<project-id>
$ 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

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 ¶

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.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
cmd
vault-plugin-secrets-gcpkms command
test
cleanup command 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.
version
cmd command

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