dbenvelope

package
v1.10.13 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: AGPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package dbenvelope seals the data key that encrypts a database recovery point.

Each set is encrypted with its own random data key, and that key is sealed here under the workspace's backup passphrase. The indirection is what makes the passphrase rotatable: re-sealing an envelope rewrites a few hundred bytes, whereas encrypting the artifacts with the passphrase directly would strand every existing set behind the secret it was taken with.

The construction matches internal/dr's identity envelope — Argon2id to a key, AES-256-GCM over the payload, a self-describing header authenticated as additional data. It is a separate implementation because dr deliberately depends on nothing else in Miabi (its restore path runs on a bare host) and its payload is an Identity, not a key.

Index

Constants

View Source
const (

	// DataKeyLen is the size of a generated data key in bytes.
	DataKeyLen = 32
)

Framing. The header is self-describing so a future format change is a clean refusal rather than a garbled decrypt.

Variables

View Source
var (
	// ErrBadPassphrase means the envelope did not authenticate: a wrong
	// passphrase, or a tampered envelope. The two are indistinguishable by design
	// — saying which would make this a decryption oracle.
	ErrBadPassphrase = errors.New("backup envelope did not decrypt: wrong passphrase or corrupt envelope")
	// ErrNotEnvelope means the bytes are not a data-key envelope at all.
	ErrNotEnvelope = errors.New("not a Miabi backup data-key envelope")
)

Functions

func IsEnvelope

func IsEnvelope(sealed string) bool

IsEnvelope reports whether a stored value looks like one of ours, so callers can tell a sealed set from one taken before envelopes existed.

func NewDataKey

func NewDataKey() (string, error)

NewDataKey returns a fresh random data key, encoded so it can be handed to the backup tools as a GPG passphrase. Base64 keeps it to one shell-safe token.

func Open

func Open(sealed, passphrase string) (string, error)

Open recovers the data key from a sealed envelope. Opening IS the passphrase check: it costs one Argon2id derivation and happens before any artifact is fetched, so a wrong passphrase is rejected without downloading anything.

func Rewrap

func Rewrap(sealed, oldPassphrase, newPassphrase string) (string, error)

Rewrap moves an envelope from one passphrase to another without touching the data key inside it, which is what makes rotation cheap: the artifacts the key encrypts are never re-read.

func Seal

func Seal(dataKey, passphrase string) (string, error)

Seal encrypts a data key under a key derived from passphrase, returning the framed envelope base64-encoded for storage in a text column. A fresh salt and nonce are drawn per call, so sealing the same key twice never produces the same bytes.

Types

type Spec

type Spec struct {
	Magic         string `json:"magic"`
	FormatVersion int    `json:"format_version"`
	KDF           string `json:"kdf"`
	ArgonTime     int    `json:"argon_time"`
	ArgonMemoryKB int    `json:"argon_memory_kib"`
	ArgonLanes    int    `json:"argon_lanes"`
	KeyLen        int    `json:"key_len"`
	SaltLen       int    `json:"salt_len"`
	NonceLen      int    `json:"nonce_len"`
	HeaderLen     int    `json:"header_len"`
	Cipher        string `json:"cipher"`
}

Spec describes the envelope format precisely enough to reimplement it without this code. It exists so a recovery kit documents the real parameters rather than a copy that can drift away from them.

func Format

func Format() Spec

Format returns the parameters this build seals with.

Jump to

Keyboard shortcuts

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