package awskms

import "gocloud.dev/secrets/awskms"

Package awskms provides a secrets implementation backed by AWS KMS. Use OpenKeeper to construct a *secrets.Keeper.

URLs

For secrets.OpenKeeper, awskms registers for the scheme "awskms". The default URL opener will use an AWS session with the default credentials and configuration.

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

awskms exposes the following type for As:

• Error: any error type returned by the service, notably smithy.APIError

package main

import (
	"context"
	"log"

	"gocloud.dev/secrets"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/secrets/awskms"
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// Use one of the following:

	// 1. By ID.
	keeperByID, err := secrets.OpenKeeper(ctx,
		"awskms://1234abcd-12ab-34cd-56ef-1234567890ab?region=us-east-1")
	if err != nil {
		log.Fatal(err)
	}
	defer keeperByID.Close()

	// 2. By alias.
	keeperByAlias, err := secrets.OpenKeeper(ctx,
		"awskms://alias/ExampleAlias?region=us-east-1")
	if err != nil {
		log.Fatal(err)
	}
	defer keeperByAlias.Close()

	// 3. By ARN. Note that ARN may contain ":" characters, which cannot be escaped
	// in the Host part of a URL, so the "awskms:///<ARN>" form should be used.
	const arn = "arn:aws:kms:us-east-1:111122223333:key/" +
		"1234abcd-12ab-34bc-56ef-1234567890ab"
	keeperByARN, err := secrets.OpenKeeper(ctx,
		"awskms:///"+arn+"?region=us-east-1")
	if err != nil {
		log.Fatal(err)
	}
	defer keeperByARN.Close()
}

Index ¶

• Constants
• Variables
• func Dial(cfg aws.Config) (*kms.Client, error)
• func OpenKeeper(client *kms.Client, 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 = "awskms"

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

Variables ¶

var DialV2 = Dial

var OpenKeeperV2 = OpenKeeper

var Set = wire.NewSet(
	Dial,
)

Set holds Wire providers for this package.

Functions ¶

func Dial ¶

func Dial(cfg aws.Config) (*kms.Client, error)

Dial gets an AWS KMS service client using the AWS SDK V2.

func OpenKeeper ¶

func OpenKeeper(client *kms.Client, keyID string, opts *KeeperOptions) *secrets.Keeper

OpenKeeper returns a *secrets.Keeper that uses AWS KMS, using SDK v2. The key ID can be in the form of an Amazon Resource Name (ARN), alias name, or alias ARN. See https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn for more details. See the package documentation for an example.

package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/config"
	"gocloud.dev/secrets/awskms"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.

	// Establish a AWS V2 Config.
	// See https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/ for more info.
	ctx := context.Background()
	cfg, err := config.LoadDefaultConfig(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Get a client to use with the KMS API.
	client, err := awskms.Dial(cfg)
	if err != nil {
		log.Fatal(err)
	}

	// Construct a *secrets.Keeper.
	keeper := awskms.OpenKeeper(client, "alias/test-secrets", nil)
	defer keeper.Close()
}

Types ¶

type KeeperOptions ¶

type KeeperOptions struct {
	// EncryptionContext parameters.
	// See https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context.
	EncryptionContext map[string]string
}

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

type URLOpener ¶

type URLOpener struct {
	// Options specifies the options to pass to OpenKeeper.
	// EncryptionContext parameters from the URL are merged in.
	Options KeeperOptions
}

URLOpener opens AWS KMS URLs like "awskms://keyID" or "awskms:///keyID".

The URL Host + Path are used as the key ID, which can be in the form of an Amazon Resource Name (ARN), alias name, or alias ARN. See https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn for more details. Note that ARNs may contain ":" characters, which cannot be escaped in the Host part of a URL, so the "awskms:///<ARN>" form should be used.

See https://pkg.go.dev/gocloud.dev/aws#V2ConfigFromURLParams.

EncryptionContext key/value pairs can be provided by providing URL parameters prefixed with "context_"; e.g., "...&context_abc=foo&context_def=bar" would result in an EncryptionContext of {abc=foo, def=bar}. See https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context.

func (*URLOpener) OpenKeeperURL ¶

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

OpenKeeperURL opens an AWS KMS Keeper based on u.

Source Files ¶

kms.go