gocloud.dev: gocloud.dev/secrets Index | Examples | Files | Directories

package secrets

import "gocloud.dev/secrets"

Package secrets provides an easy and portable way to encrypt and decrypt messages.

Subpackages contain distinct implementations of secrets for various providers, including Cloud and on-premise solutions. For example, "localsecrets" supports encryption/decryption using a locally provided key. Your application should import one of these provider-specific subpackages and use its exported function(s) to create a *Keeper; do not use the NewKeeper function in this package. For example:

keeper := localsecrets.NewKeeper(myKey)
encrypted, err := keeper.Encrypt(ctx.Background(), []byte("text"))
...

Then, write your application code using the *Keeper type. You can easily reconfigure your initialization code to choose a different provider. You can develop your application locally using localsecrets, or deploy it to multiple Cloud providers. You may find http://github.com/google/wire useful for managing your initialization code.

Alternatively, you can construct a *Keeper via a URL and OpenKeeper. See https://gocloud.dev/concepts/urls/ for more information.

OpenCensus Integration

OpenCensus supports tracing and metric collection for multiple languages and backend providers. See https://opencensus.io.

This API collects OpenCensus traces and metrics for the following methods:

- Encrypt
- Decrypt

All trace and metric names begin with the package import path. The traces add the method name. For example, "gocloud.dev/secrets/Encrypt". The metrics are "completed_calls", a count of completed method calls by provider, method and status (error code); and "latency", a distribution of method latency by provider and method. For example, "gocloud.dev/secrets/latency".

To enable trace collection in your application, see "Configure Exporter" at https://opencensus.io/quickstart/go/tracing. To enable metric collection in your application, see "Exporting stats" at https://opencensus.io/quickstart/go/metrics.

Code:

// This example is specific to the gcpkms implementation; it
// demonstrates access to the underlying google.golang.org/grpc/status.Status
// type.
// The types exposed for As by gcpkms are documented in
// https://godoc.org/gocloud.dev/secrets/gcpkms#hdr-As
ctx := context.Background()

const url = "gcpkms://projects/proj/locations/global/keyRings/test/ring/wrongkey"
keeper, err := secrets.OpenKeeper(ctx, url)
if err != nil {
    log.Fatal(err)
}
defer keeper.Close()

plaintext := []byte("Go CDK secrets")
_, err = keeper.Encrypt(ctx, plaintext)
if err != nil {
    var s *status.Status
    if keeper.ErrorAs(err, &s) {
        fmt.Println(s.Code())
    }
}

Code:

ctx := context.Background()

// Create a Keeper using a URL.
// This example uses "localsecrets", the in-memory implementation.
// We need to add a blank import line to register the localsecrets provider's
// URLOpener, which implements secrets.KeeperURLOpener:
// import _ "gocloud.dev/secrets/localsecrets"
// localsecrets registers for the "base64key" scheme.
// All secrets.OpenKeeper URLs also work with "secrets+" or "secrets+keeper+" prefixes,
// e.g., "secrets+base64key://..." or "secrets+variable+base64key://...".
// All secrets URLs also work with the "secrets+" prefix, e.g., "secrets+base64key://".
k, err := secrets.OpenKeeper(ctx, "base64key://smGbjm71Nxd1Ig5FS0wj9SlbzAIrnolCz9bQQ6uAhl4=")
if err != nil {
    log.Fatal(err)
}
defer k.Close()

// Now we can use k to encrypt/decrypt.
plaintext := []byte("Go CDK Secrets")
ciphertext, err := k.Encrypt(ctx, plaintext)
if err != nil {
    log.Fatal(err)
}
decrypted, err := k.Decrypt(ctx, ciphertext)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(decrypted))

Output:

Go CDK Secrets

Index

Examples

Package Files

secrets.go

Variables

var NewKeeper = newKeeper

NewKeeper is intended for use by provider implementations.

var (

    // OpenCensusViews are predefined views for OpenCensus metrics.
    // The views include counts and latency distributions for API method calls.
    // See the example at https://godoc.org/go.opencensus.io/stats/view for usage.
    OpenCensusViews = oc.Views(pkgName, latencyMeasure)
)

type Keeper Uses

type Keeper struct {
    // contains filtered or unexported fields
}

Keeper does encryption and decryption. To create a Keeper, use constructors found in provider-specific subpackages.

func OpenKeeper Uses

func OpenKeeper(ctx context.Context, urlstr string) (*Keeper, error)

OpenKeeper opens the Keeper identified by the URL given. See the URLOpener documentation in provider-specific subpackages for details on supported URL formats, and https://gocloud.dev/concepts/urls for more information.

func (*Keeper) Close Uses

func (k *Keeper) Close() error

Close releases any resources used for the Keeper.

func (*Keeper) Decrypt Uses

func (k *Keeper) Decrypt(ctx context.Context, ciphertext []byte) (plaintext []byte, err error)

Decrypt decrypts the ciphertext and returns the plaintext.

func (*Keeper) Encrypt Uses

func (k *Keeper) Encrypt(ctx context.Context, plaintext []byte) (ciphertext []byte, err error)

Encrypt encrypts the plaintext and returns the cipher message.

func (*Keeper) ErrorAs Uses

func (k *Keeper) ErrorAs(err error, i interface{}) bool

ErrorAs converts i to provider-specific types. See https://gocloud.dev/concepts/as/ for background information and the provider-specific package documentation for the specific types supported for that provider.

ErrorAs panics if i is nil or not a pointer. ErrorAs returns false if err == nil.

type KeeperURLOpener Uses

type KeeperURLOpener interface {
    OpenKeeperURL(ctx context.Context, u *url.URL) (*Keeper, error)
}

KeeperURLOpener represents types that can open Keepers based on a URL. The opener must not modify the URL argument. OpenKeeperURL must be safe to call from multiple goroutines.

This interface is generally implemented by types in driver packages.

type URLMux Uses

type URLMux struct {
    // contains filtered or unexported fields
}

URLMux is a URL opener multiplexer. It matches the scheme of the URLs against a set of registered schemes and calls the opener that matches the URL's scheme. See https://gocloud.dev/concepts/urls/ for more information.

The zero value is a multiplexer with no registered schemes.

func DefaultURLMux Uses

func DefaultURLMux() *URLMux

DefaultURLMux returns the URLMux used by OpenKeeper.

Driver packages can use this to register their KeeperURLOpener on the mux.

func (*URLMux) KeeperSchemes Uses

func (mux *URLMux) KeeperSchemes() []string

KeeperSchemes returns a sorted slice of the registered Keeper schemes.

func (*URLMux) OpenKeeper Uses

func (mux *URLMux) OpenKeeper(ctx context.Context, urlstr string) (*Keeper, error)

OpenKeeper calls OpenKeeperURL with the URL parsed from urlstr. OpenKeeper is safe to call from multiple goroutines.

func (*URLMux) OpenKeeperURL Uses

func (mux *URLMux) OpenKeeperURL(ctx context.Context, u *url.URL) (*Keeper, error)

OpenKeeperURL dispatches the URL to the opener that is registered with the URL's scheme. OpenKeeperURL is safe to call from multiple goroutines.

func (*URLMux) RegisterKeeper Uses

func (mux *URLMux) RegisterKeeper(scheme string, opener KeeperURLOpener)

RegisterKeeper registers the opener with the given scheme. If an opener already exists for the scheme, RegisterKeeper panics.

func (*URLMux) ValidKeeperScheme Uses

func (mux *URLMux) ValidKeeperScheme(scheme string) bool

ValidKeeperScheme returns true iff scheme has been registered for Keepers.

Directories

PathSynopsis
awskmsPackage awskms provides a secrets implementation backed by AWS KMS.
azurekeyvaultPackage azurekeyvault provides a secrets implementation backed by Azure KeyVault.
driverPackage driver defines interfaces to be implemented for providers of the secrets package.
drivertestPackage drivertest provides a conformance test for implementations of the secrets driver.
gcpkmsPackage gcpkms provides a secrets implementation backed by Google Cloud KMS.
localsecretsPackage localsecrets provides a secrets implementation using a locally locally provided symmetric key.
vaultPackage vault provides a secrets implementation using the Transit Secrets Engine of Vault by Hashicorp.

Package secrets imports 7 packages (graph) and is imported by 9 packages. Updated 2019-05-17. Refresh now. Tools for package owners.