secrets

Documentation

Overview

Package secrets defines a pluggable abstraction over secret managers.

The core package ships two providers with no external dependencies: "FILESYSTEM" and "IN_MEMORY". Cloud-backed providers live in sub-packages that self-register via a blank import, so their SDKs are only compiled into binaries that actually use them:

import _ "github.com/mikehelmick/go-bananas/secrets/gcp"   // GOOGLE_SECRET_MANAGER
import _ "github.com/mikehelmick/go-bananas/secrets/aws"   // AWS_SECRETS_MANAGER
import _ "github.com/mikehelmick/go-bananas/secrets/azure" // AZURE_KEY_VAULT
import _ "github.com/mikehelmick/go-bananas/secrets/vault" // HASHICORP_VAULT

Further providers can be added the same way: a sub-package whose init function calls RegisterManager.

Select a provider by name through Config.Type and obtain it with SecretManagerFor. Resolver integrates with github.com/sethvargo/go-envconfig to transparently resolve "secret://" references during configuration loading.

Index

• Constants
• func RegisterManager(name string, fn SecretManagerFunc)
• func RegisteredManagers() []string
• func Resolver(sm SecretManager, config *Config) envconfig.MutatorFunc
• type Cacher
  • func (sm *Cacher) GetSecretValue(ctx context.Context, name string) (string, error)
• type Config
• type Filesystem
  • func (sm *Filesystem) CreateSecretVersion(_ context.Context, parent string, data []byte) (string, error)
  • func (sm *Filesystem) DestroySecretVersion(_ context.Context, name string) error
  • func (sm *Filesystem) GetSecretValue(_ context.Context, name string) (string, error)
• type InMemory
  • func (sm *InMemory) CreateSecretVersion(_ context.Context, parent string, data []byte) (string, error)
  • func (sm *InMemory) DestroySecretVersion(_ context.Context, k string) error
  • func (sm *InMemory) GetSecretValue(_ context.Context, k string) (string, error)
• type JSONExpander
  • func (sm *JSONExpander) GetSecretValue(ctx context.Context, name string) (string, error)
• type SecretManager
  • func NewFilesystem(_ context.Context, cfg *Config) (SecretManager, error)
  • func NewInMemory(_ context.Context, _ *Config) (SecretManager, error)
  • func NewInMemoryFromMap(_ context.Context, m map[string]string) (SecretManager, error)
  • func SecretManagerFor(ctx context.Context, cfg *Config) (SecretManager, error)
  • func WrapCacher(_ context.Context, sm SecretManager, ttl time.Duration) (SecretManager, error)
  • func WrapJSONExpander(_ context.Context, sm SecretManager) (SecretManager, error)
• type SecretManagerFunc
• type SecretVersionManager

Examples

• SecretManagerFor

Constants

const (
	// SecretPrefix marks an environment-variable value that should be resolved
	// through the secret manager.
	SecretPrefix = "secret://"

	// FileSuffix, when appended to a "secret://" value, causes the resolved
	// secret to be written to a file and the file path returned instead.
	FileSuffix = "?target=file"
)

Functions

func RegisterManager

func RegisterManager(name string, fn SecretManagerFunc)

RegisterManager registers a secret manager constructor under name. It panics if name is already registered. Providers call it from an init function.

func RegisteredManagers

func RegisteredManagers() []string

RegisteredManagers returns the sorted names of all registered secret managers.

func Resolver

func Resolver(sm SecretManager, config *Config) envconfig.MutatorFunc

Resolver returns an github.com/sethvargo/go-envconfig.MutatorFunc that resolves "secret://" references through sm during configuration loading. Comma-separated values are resolved element by element. If sm is nil, Resolver returns nil (no mutation).

Types

type Cacher

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

Cacher wraps a SecretManager, caching resolved values for a configurable TTL to reduce calls to the underlying provider.

func (*Cacher) GetSecretValue

func (sm *Cacher) GetSecretValue(ctx context.Context, name string) (string, error)

GetSecretValue returns the cached value if present and unexpired, otherwise it fetches from the wrapped manager and caches the result.

type Config

type Config struct {
	// Type selects the registered provider by name (e.g. "FILESYSTEM",
	// "IN_MEMORY", "GOOGLE_SECRET_MANAGER").
	Type string `env:"SECRET_MANAGER, default=IN_MEMORY"`

	// SecretsDir is where secrets resolved to files (via the "?target=file"
	// suffix) are written.
	SecretsDir string `env:"SECRETS_DIR, default=/var/run/secrets"`

	// SecretCacheTTL is how long resolved secret values are cached.
	SecretCacheTTL time.Duration `env:"SECRET_CACHE_TTL, default=5m"`

	// SecretExpansion enables JSON expansion of secret values (see
	// [WrapJSONExpander]).
	SecretExpansion bool `env:"SECRET_EXPANSION, default=false"`

	// FilesystemRoot is the root path for the FILESYSTEM provider.
	FilesystemRoot string `env:"SECRET_FILESYSTEM_ROOT"`
}

Config configures which secret manager to use and how. The struct tags are compatible with github.com/sethvargo/go-envconfig.

type Filesystem

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

Filesystem is a filesystem-backed secret manager, intended for local development and testing. Each secret is a file under the configured root.

func (*Filesystem) CreateSecretVersion

func (sm *Filesystem) CreateSecretVersion(_ context.Context, parent string, data []byte) (string, error)

CreateSecretVersion writes a new version file under root/parent and returns its reference.

func (*Filesystem) DestroySecretVersion

func (sm *Filesystem) DestroySecretVersion(_ context.Context, name string) error

DestroySecretVersion removes the version file. A missing file is not an error.

func (*Filesystem) GetSecretValue

func (sm *Filesystem) GetSecretValue(_ context.Context, name string) (string, error)

GetSecretValue returns the contents of the file at root/name.

type InMemory

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

InMemory is an in-memory secret manager, primarily used for testing.

func (*InMemory) CreateSecretVersion

func (sm *InMemory) CreateSecretVersion(_ context.Context, parent string, data []byte) (string, error)

CreateSecretVersion stores data under a new version of parent and returns its reference.

func (*InMemory) DestroySecretVersion

func (sm *InMemory) DestroySecretVersion(_ context.Context, k string) error

DestroySecretVersion removes the named secret version.

func (*InMemory) GetSecretValue

func (sm *InMemory) GetSecretValue(_ context.Context, k string) (string, error)

GetSecretValue returns the named secret, or an error if it does not exist.

type JSONExpander

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

JSONExpander wraps a SecretManager and adds JSON field extraction: a secret name containing a period selects a field from a JSON-valued secret.

func (*JSONExpander) GetSecretValue

func (sm *JSONExpander) GetSecretValue(ctx context.Context, name string) (string, error)

GetSecretValue returns the named secret. If name contains a period, the part before the first period names a secret whose value is parsed as JSON, and the remaining dotted path selects a (possibly nested) string field.

For example, if the secret "psqlcreds" holds {"username":"gandalf","password":"abc"}, then GetSecretValue(ctx, "psqlcreds.username") returns "gandalf".

type SecretManager

type SecretManager interface {
	// GetSecretValue returns the value of the secret with the given name.
	GetSecretValue(ctx context.Context, name string) (string, error)
}

SecretManager is the minimum interface for reading secret values.

func NewFilesystem

func NewFilesystem(_ context.Context, cfg *Config) (SecretManager, error)

NewFilesystem creates a filesystem-backed secret manager rooted at cfg.FilesystemRoot (created if it does not exist).

func NewInMemory

func NewInMemory(_ context.Context, _ *Config) (SecretManager, error)

NewInMemory creates an empty in-memory secret manager.

func NewInMemoryFromMap

func NewInMemoryFromMap(_ context.Context, m map[string]string) (SecretManager, error)

NewInMemoryFromMap creates an in-memory secret manager seeded from m.

func SecretManagerFor

func SecretManagerFor(ctx context.Context, cfg *Config) (SecretManager, error)

SecretManagerFor constructs the secret manager named by cfg.Type. It returns an error if no provider with that name is registered (which usually means the provider's sub-package was not blank-imported).

Example

package main

import (
	"context"
	"fmt"

	"github.com/mikehelmick/go-bananas/secrets"
)

func main() {
	// The FILESYSTEM and IN_MEMORY providers are registered by the core package.
	// Select one by name via Config.Type.
	sm, err := secrets.SecretManagerFor(context.Background(), &secrets.Config{
		Type: "IN_MEMORY",
	})
	if err != nil {
		panic(err)
	}

	// IN_MEMORY also implements SecretVersionManager.
	vm := sm.(secrets.SecretVersionManager)
	ref, _ := vm.CreateSecretVersion(context.Background(), "db-password", []byte("s3cret"))
	value, _ := sm.GetSecretValue(context.Background(), ref)

	fmt.Println(value)
}

Output:
s3cret

func WrapCacher

func WrapCacher(_ context.Context, sm SecretManager, ttl time.Duration) (SecretManager, error)

WrapCacher wraps sm with an in-memory cache whose entries expire after ttl.

func WrapJSONExpander

func WrapJSONExpander(_ context.Context, sm SecretManager) (SecretManager, error)

WrapJSONExpander wraps sm with JSON-expansion behavior (see JSONExpander).

type SecretManagerFunc

type SecretManagerFunc func(context.Context, *Config) (SecretManager, error)

SecretManagerFunc constructs a SecretManager from configuration.

type SecretVersionManager

type SecretVersionManager interface {
	SecretManager

	// CreateSecretVersion creates a new version of the named secret with the
	// given data, returning a reference to the created version.
	CreateSecretVersion(ctx context.Context, parent string, data []byte) (string, error)

	// DestroySecretVersion destroys the named secret version. Destroying a
	// version that does not exist is not an error.
	DestroySecretVersion(ctx context.Context, name string) error
}

SecretVersionManager is a SecretManager that can also create and destroy secret versions.