seal

package
v0.6.50 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package seal encrypts what a service keeps and has to read back — a receiver's signing secret, a provider's token — so a copy of its database or of a backup holds ciphertext only. It is a configuration section and a dependency, like a database connection:

type Config struct {
    config.Backplane `json:"backplane"`
    Seal seal.Config `json:"seal"` // KOMEET_SEAL_KEY, KOMEET_SEAL_PREVIOUS
}

sealer := deps.NewDependency(root, seal.New(cfg.Seal), deps.Name("seal"))
sealed, err := sealer.Get().Seal(ctx, []byte(secret), []byte(subscriptionID))
secret, err := sealer.Get().Open(ctx, sealed, []byte(subscriptionID))

The associated data (aad) binds a sealed value to what it belongs to: it is not stored, Open needs the same, and a value copied to another row does not open there.

The keys are AES-256-GCM keys of the section: key seals and opens, previous only opens. A sealed value names its key (by a hash of it), so rotation is: generate a key (GenerateKey), set it as key and the old one as previous, Rewrap what is stored, then drop previous.

With vault set, Vault's Transit engine seals instead (envelope encryption: a fresh data key per value, wrapped by the Transit key, which never leaves Vault), and the dependency probes Vault. The section's keys, when still set, open what they sealed, and Rewrap moves it to Vault; after a Transit key rotation Rewrap moves values to its latest version.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrConfig: the section has no key, or a key is not base64 of 32
	// bytes.
	ErrConfig = errors.New("seal: invalid configuration")
	// ErrOpen: the value is not sealed by these keys, was changed, or the
	// aad differs.
	ErrOpen = errors.New("seal: cannot open")
)

Errors.

View Source
var ErrVault = errors.New("seal: vault")

ErrVault: Vault answered with an error or could not be reached.

Functions

func GenerateKey

func GenerateKey() string

GenerateKey is a new random key, base64.

func New

func New(cfg Config) deps.Provider[Sealer]

New is the provider of the section's sealer.

Types

type Config

type Config struct {
	// Key seals and opens: base64 of 32 random bytes (GenerateKey).
	Key config.Secret `desc:"Active key: base64 of 32 random bytes; seals and opens." json:"key,omitempty"`
	// Previous keys only open: comma-separated, while values are rewrapped.
	Previous config.Secret `desc:"Previous keys, comma-separated: they only open, during rotation." json:"previous,omitempty"`
	// Vault seals instead of key when its addr is set; key and previous
	// then only open what they sealed before.
	Vault Vault `desc:"Vault Transit: when set it seals, the keys only open." json:"vault"`
}

Config is the section of the keys.

func (Config) Validate

func (c Config) Validate() error

Validate checks the section.

type Sealer

type Sealer interface {
	// Seal encrypts plaintext under the active key, bound to aad.
	Seal(ctx context.Context, plaintext, aad []byte) ([]byte, error)
	// Open decrypts what Seal returned with the same aad, under the active
	// key or a previous one.
	Open(ctx context.Context, sealed, aad []byte) ([]byte, error)
	// Rewrap seals sealed again under the active key; changed is false,
	// and sealed returns as is, when it is under the active key already.
	Rewrap(ctx context.Context, sealed, aad []byte) (out []byte, changed bool, err error)
}

Sealer seals and opens values. It is immutable and safe for concurrent use.

func Open

func Open(cfg Config) (Sealer, error)

Open is the section's sealer, outside of a dependency (tools, tests).

type Vault added in v0.6.49

type Vault struct {
	// Addr is Vault's URL; empty: no Vault, the section's keys seal.
	Addr  string        `desc:"Vault URL, e.g. https://vault:8200; empty: the section's keys seal." json:"addr,omitempty"`
	Token config.Secret `desc:"Token with datakey, decrypt and rewrap on the key."                  json:"token,omitempty"`
	// Key is the Transit key's name (type aes256-gcm96).
	Key       string        `desc:"Name of the Transit key."                     json:"key,omitempty"`
	Mount     string        `desc:"Mount path of the Transit engine."            json:"mount"               schemapb:"default=transit"`
	Namespace string        `desc:"Vault Enterprise namespace; empty: the root." json:"namespace,omitempty"`
	TLS       config.TLS    `desc:"TLS of the connection to Vault."              json:"tls"`
	Timeout   time.Duration `desc:"Bound of one call to Vault."                  json:"timeout"             schemapb:"default=10s"`
}

Vault is the Transit engine of a HashiCorp Vault (or OpenBao): the key never leaves it. Every Seal takes a fresh data key from Transit and keeps it wrapped next to the value; Open has Transit unwrap it.

Give the sealer a Transit key of its own and grant no one encrypt on it: whoever can encrypt with the key can wrap a data key they chose and forge a value Open accepts. The token needs datakey, decrypt and rewrap.

func (Vault) Enabled added in v0.6.49

func (v Vault) Enabled() bool

Enabled reports whether Vault seals.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL