gcpkms

Documentation

Overview

Package gcpkms provides a secrets implementation backed by Google Cloud KMS. Use OpenKeeper to construct a *secrets.Keeper.

URLs

For secrets.OpenKeeper, gcpkms registers for the scheme "gcpkms". The default URL opener will create a connection using use default credentials from the environment, as described in https://cloud.google.com/docs/authentication/production. To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.

As

gcpkms exposes the following type for As:

• Error: *google.golang.org/grpc/status.Status

Example (OpenFromURL)

package main

import (
	"context"
	"log"

	"gocloud.dev/secrets"
)

func main() {
	ctx := context.Background()

	// secrets.OpenKeeper creates a *secrets.Keeper from a URL.
	// The host + path are the key resourceID; see
	// https://cloud.google.com/kms/docs/object-hierarchy#key
	// for more information.
	keeper, err := secrets.OpenKeeper(ctx, "gcpkms://projects/MYPROJECT/locations/MYLOCATION/keyRings/MYKEYRING/cryptoKeys/MYKEY")
	if err != nil {
		log.Fatal(err)
	}
	defer keeper.Close()
}

Index

• Constants
• Variables
• func Dial(ctx context.Context, ts gcp.TokenSource) (*cloudkms.KeyManagementClient, func(), error)
• func KeyResourceID(projectID, location, keyRing, key string) string
• func OpenKeeper(client *cloudkms.KeyManagementClient, keyID string, opts *KeeperOptions) *secrets.Keeper
• type KeeperOptions
• type URLOpener
  • func (o *URLOpener) OpenKeeperURL(ctx context.Context, u *url.URL) (*secrets.Keeper, error)

Examples

• Package (OpenFromURL)
• OpenKeeper

Constants

const Scheme = "gcpkms"

Scheme is the URL scheme gcpkms registers its URLOpener under on secrets.DefaultMux.

Variables

var Set = wire.NewSet(
	Dial,
	KeeperOptions{},
	URLOpener{},
)

Set holds Wire providers for this package.

Functions

func Dial

func Dial(ctx context.Context, ts gcp.TokenSource) (*cloudkms.KeyManagementClient, func(), error)

Dial returns a client to use with Cloud KMS and a clean-up function to close the client after used.

func KeyResourceID

func KeyResourceID(projectID, location, keyRing, key string) string

KeyResourceID constructs a key resourceID for GCP KMS. See https://cloud.google.com/kms/docs/object-hierarchy#key for more details.

func OpenKeeper

func OpenKeeper(client *cloudkms.KeyManagementClient, keyID string, opts *KeeperOptions) *secrets.Keeper

OpenKeeper returns a *secrets.Keeper that uses Google Cloud KMS. See https://cloud.google.com/kms/docs/object-hierarchy#key for more details. See the package documentation for an example.

Example

package main

import (
	"context"
	"log"

	"gocloud.dev/secrets/gcpkms"
)

func main() {
	// Get a client to use with the KMS API.
	ctx := context.Background()
	client, done, err := gcpkms.Dial(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	// Close the connection when done.
	defer done()

	// Construct a *secrets.Keeper.
	keeper := gcpkms.OpenKeeper(
		client,
		// Get the key resource ID.
		// See https://cloud.google.com/kms/docs/object-hierarchy#key for more
		// information.
		// You can also use gcpkms.KeyResourceID to construct the string.
		"projects/MYPROJECT/locations/MYLOCATION/keyRings/MYKEYRING/cryptoKeys/MYKEY",
		nil,
	)
	defer keeper.Close()

	// Now we can use keeper to encrypt or decrypt.
	plaintext := []byte("Hello, Secrets!")
	ciphertext, err := keeper.Encrypt(ctx, plaintext)
	if err != nil {
		log.Fatal(err)
	}
	decrypted, err := keeper.Decrypt(ctx, ciphertext)
	if err != nil {
		log.Fatal(err)
	}
	_ = decrypted
}

Types

type KeeperOptions

type KeeperOptions struct{}

KeeperOptions controls Keeper behaviors. It is provided for future extensibility.

type URLOpener

type URLOpener struct {
	// Client must be non-nil and be authenticated with "cloudkms" scope or equivalent.
	Client *cloudkms.KeyManagementClient

	// Options specifies the default options to pass to OpenKeeper.
	Options KeeperOptions
}

URLOpener opens GCP KMS URLs like "gcpkms://projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEY_RING]/cryptoKeys/[KEY]".

The URL host+path are used as the key resource ID; see https://cloud.google.com/kms/docs/object-hierarchy#key for more details.

No query parameters are supported.

func (*URLOpener) OpenKeeperURL

func (o *URLOpener) OpenKeeperURL(ctx context.Context, u *url.URL) (*secrets.Keeper, error)

OpenKeeperURL opens the GCP KMS URLs.