secrets

Documentation

Overview

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-prem 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.

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.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"gocloud.dev/secrets/localsecrets"
)

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

	// Construct a *secrets.Keeper from one of the secrets subpackages.
	// This example uses localsecrets.
	keeper := localsecrets.NewKeeper(localsecrets.ByteKey("secret key"))

	// Now we can use keeper to Encrypt.
	plaintext := []byte("Go CDK Secrets")
	ciphertext, err := keeper.Encrypt(ctx, plaintext)
	if err != nil {
		log.Fatal(err)
	}

	// And/or Decrypt.
	decrypted, err := keeper.Decrypt(ctx, ciphertext)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(decrypted))

}

Output:

Go CDK Secrets

Index

• Variables
• type Keeper
  • func (k *Keeper) Decrypt(ctx context.Context, ciphertext []byte) (plaintext []byte, err error)
  • func (k *Keeper) Encrypt(ctx context.Context, plaintext []byte) (ciphertext []byte, err error)
  • func (k *Keeper) ErrorAs(err error, i interface{}) bool

Examples

• Package

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)
)

Types

type Keeper

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 (*Keeper) Decrypt

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

Decrypt decrypts the ciphertext and returns the plaintext.

func (*Keeper) Encrypt

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

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

ErrorAs converts i to provider-specific error types when you want to directly handle the raw error types returned by the provider. This means that you will write some provider-specific code to handle the error, so use with care.

See the documentation for the subpackage used to instantiate Keeper to see which error type(s) are supported.

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