secrets

Documentation

Overview

Package secrets assembles a namespace's secrets from the objects a backend holds for it: an append-only set of per-write segments over zero or more folded snapshots. Each write appends a new, uniquely named segment, so concurrent writers never overwrite one another. Reads fold the snapshots and segments together by a Lamport clock: last write per key wins, ties between machines are reported as conflicts. Compaction collapses what it reads into a fresh snapshot and deletes the objects it folded.

Every object is one age message sealed under the master key, and every object is bound to the vault's authenticated header by a manifest entry (a keyed MAC of its plaintext, see internal/crypto). A fold trusts the manifest, not the storage listing: a manifest-listed object that is missing, altered, or relocated is an alarm, and an object the manifest does not know is folded in only when it can be nothing but an honest in-flight write.

Index

• Constants
• func Exists(ctx context.Context, store backend.Backend, name string) (bool, error)
• type Conflict
• type Meta
• type Namespace
  • func For(store backend.Backend, name string, master *crypto.MasterKey, machine string, ...) *Namespace
  • func (n *Namespace) Append(ctx context.Context, prev *State, seq int, w Write) (*State, string, crypto.ManifestEntry, error)
  • func (n *Namespace) Compact(ctx context.Context, commit func(crypto.ManifestDelta) error) error
  • func (n *Namespace) Fold(ctx context.Context) (*State, error)
• type State
  • func (s *State) HasHistory() bool
  • func (s *State) SegmentCount() int
• type Write

Constants

const DefaultCompactThreshold = 16

DefaultCompactThreshold is the segment count at or above which a write triggers automatic compaction. It bounds the objects a cold read folds, so reads stay fast without anyone running `notenv compact` by hand.

Functions

func Exists

func Exists(ctx context.Context, store backend.Backend, name string) (bool, error)

Exists reports whether a namespace has any stored object yet. It only lists, so it needs no master key.

Types

type Conflict

type Conflict struct {
	Key      string
	Winner   string
	Shadowed []string
}

Conflict reports a key written concurrently on more than one machine (equal Lamport). Winner's value is the one kept; the others are shadowed but remain recoverable from their segments until the next compaction.

type Meta

type Meta struct {
	Description string
	TS          int64
}

Meta is a live key's advisory metadata: what the secret is for and when its winning write happened (wall-clock Unix seconds; 0 means the write predates timestamps). Advisory means exactly that: nothing orders or trusts by it.

type Namespace

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

Namespace reads and writes one namespace's secrets through a backend, sealing every object under master. machine identifies and orders this machine's writes so two machines never produce the same segment. manifest is the verified header's object manifest; folds check every object against it.

func For

func For(store backend.Backend, name string, master *crypto.MasterKey, machine string, manifest map[string]crypto.ManifestEntry) *Namespace

For binds a namespace to a backend, master key, and the verified header's manifest.

func (*Namespace) Append

func (n *Namespace) Append(ctx context.Context, prev *State, seq int, w Write) (*State, string, crypto.ManifestEntry, error)

Append writes one key change as a new segment and returns the resulting state, the object key the segment landed under (so the caller can remove the write again if recording it in the manifest fails), and the manifest entry that records it. prev is the fold this write builds on; its Lamport sets the new clock.

func (*Namespace) Compact

func (n *Namespace) Compact(ctx context.Context, commit func(crypto.ManifestDelta) error) error

Compact folds the namespace into a single fresh snapshot and removes the objects it folded, adopting any in-flight writes it found along the way. It writes the new snapshot before deleting anything and only deletes objects it read, so a write that lands concurrently (under a name it never listed) is never lost.

commit makes the snapshot authoritative: it must apply the given manifest delta to the vault header (under the compare-and-swap, which also confirms the master this compaction sealed with is still the vault's master). If it errors, Compact removes its own snapshot and returns with the namespace untouched. After the subsumed objects are deleted, commit is called once more, best-effort, to prune their now-pointless entries.

func (*Namespace) Fold

func (n *Namespace) Fold(ctx context.Context) (*State, error)

Fold reads every object in the namespace and resolves the current secrets.

type State

type State struct {
	Secrets   map[string]string
	Meta      map[string]Meta
	Conflicts []Conflict
	// Adoptable lists objects the fold trusted as honest in-flight writes (see
	// classify) but the manifest does not record yet, with the entries a writer
	// should add to adopt them.
	Adoptable map[string]crypto.ManifestEntry
	// Prunable lists manifest entries marked folded whose objects are confirmed
	// gone; any writer may drop them.
	Prunable []string
	// Strays lists unknown snapshots the fold ignored (a compaction that crashed
	// between writing its snapshot and recording it); `notenv compact` removes
	// them.
	Strays []string
	// contains filtered or unexported fields
}

State is a folded namespace: the resolved secrets and any same-key conflicts detected during the fold. lamport is the highest Lamport folded, the basis for the next write's clock; segments is how many segment objects it folded.

func (*State) HasHistory

func (s *State) HasHistory() bool

HasHistory reports whether any write has ever been folded into this state; false means the namespace is untouched (distinct from one emptied by deletes).

func (*State) SegmentCount

func (s *State) SegmentCount() int

SegmentCount is how many uncompacted segment objects this fold read, the signal a caller uses to decide whether the next write should compact.

type Write

type Write struct {
	Key         string
	Value       string
	Description string
	TS          int64
	Deleted     bool
}

Write is one key change to append: a value (with optional advisory metadata) or a deletion. TS is the write's wall-clock Unix seconds, supplied by the caller so this package never reads a clock; 0 omits it.