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 ¶
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.
var ErrVault = errors.New("seal: vault")
ErrVault: Vault answered with an error or could not be reached.
Functions ¶
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.
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.
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.