keyforge

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

type Clock interface {
	Now() time.Time
}

type DEKRecord struct {
	ID         envelope.ID
	Purpose    Purpose
	Subject    string // empty for a purpose-wide key
	Epoch      uint32 // starts at 1 and increases per purpose and subject
	Algorithm  algorithm.ID
	KEKID      envelope.ID
	KEKVersion uint32
	Wrapped    []byte
	State      DEKState
	Reserved   uint64 // high-water mark of reserved encryptions
	CreatedAt  time.Time
	// WrappedUnder lists every KEK version this key has been wrapped under, in
	// order, ending with the current one. A backup of the registry taken at any
	// point holds the key wrapped under one of them, which is what decides when
	// destroying the key is complete.
	WrappedUnder []KEKVersionRef
}

type DEKState uint8

type Envelope = envelope.Envelope

type Info struct {
	Mode    envelope.Mode
	Subject string
	// Epoch is the data key's epoch (reference mode).
	Epoch uint32
	// KEKVersion is the KEK version that wraps the key (inline mode).
	KEKVersion uint32
	// Stale reports that the envelope was written under a data key that is no
	// longer current, or an inline key under an older KEK version, so the
	// caller can rewrite it on its next write. It is advisory: it is computed
	// from a cached view, and a registry outage can hide it.
	Stale bool
}

type KEKVersion struct {
	Ref     provider.KeyRef
	Version uint32
}

type KEKVersionRef struct {
	KEKID   envelope.ID
	Version uint32
}

type KeyRef = provider.KeyRef

type KeySpec = provider.KeySpec

type Options struct {
	// Store is the registry. Required.
	Store Store
	// Providers are the KEK holders, matched to a key by [provider.Provider]
	// Name. At least one is required.
	Providers []provider.Provider
	// Selector chooses algorithms and enforces the profile. The zero value
	// uses [algorithm.DefaultProfile].
	Selector *algorithm.Selector
	// Purposes lists the purposes this client may use. Anything else fails
	// with [ErrUnknownPurpose].
	Purposes map[Purpose]PurposeConfig
	// Clock defaults to the system clock.
	Clock Clock
	// Entropy supplies data keys and identifiers, and defaults to
	// crypto/rand. Tests inject a deterministic reader. Nonces come from the
	// AEAD's own generator and are not drawn from it.
	Entropy io.Reader
	// CacheTTL and CacheSize bound the unwrapped-key cache.
	CacheTTL  time.Duration
	CacheSize int
	// EncryptionCap and ReserveBlock set the per-key cap and the size of the
	// blocks reserved from the registry. Zero uses the defaults.
	EncryptionCap uint64
	ReserveBlock  uint64
	// MaxAge is how long a data key epoch is used for writes. Zero means
	// [DefaultMaxAge].
	MaxAge time.Duration
	// Metrics receives operation rates, failures and cache behavior. The
	// default discards them.
	Metrics metrics.Metrics
}

type Purpose string

type PurposeConfig struct {
	// Algorithms narrows the algorithms used for this purpose. See
	// [algorithm.Selection].
	Algorithms algorithm.Selection
	// EncryptionCap overrides [Options.EncryptionCap] for this purpose. Zero
	// uses the client's.
	EncryptionCap uint64
	// MaxAge overrides [Options.MaxAge] for this purpose. Zero uses the
	// client's.
	MaxAge time.Duration
	// PerSubject gives each subject (a user, a tenant) data key epochs of its
	// own, so that destroying one subject's keys makes that subject's data
	// unrecoverable wherever it was copied. A per-subject purpose is written
	// with [Client.EncryptFor]; any other purpose is written with
	// [Client.Encrypt].
	PerSubject bool
}

type Store interface {
	// ActiveKEK returns the KEK version new data keys for purpose are wrapped
	// under. It returns [ErrNoActiveKEK] if the purpose has none.
	ActiveKEK(ctx context.Context, purpose Purpose) (KEKVersion, error)

	// KEK returns the provider reference for a KEK identifier. It returns
	// [ErrKEKNotFound] for an identifier the registry does not hold.
	KEK(ctx context.Context, id envelope.ID) (provider.KeyRef, error)

	// KEKVersionUsable reports whether data keys wrapped under a KEK version
	// may be unwrapped: it is active, decrypt-only, retire-requested or
	// compromised. A pending, retired or destroyed version is not usable, even
	// while the provider still holds its material. It returns
	// [ErrKEKNotFound] for a KEK the registry does not hold, and false for a
	// version it does not hold.
	KEKVersionUsable(ctx context.Context, id envelope.ID, version uint32) (bool, error)

	// CurrentDEK returns the data key that new writes for purpose and subject
	// use. It returns [ErrDEKNotFound] if none exists yet.
	CurrentDEK(ctx context.Context, purpose Purpose, subject string) (DEKRecord, error)

	// GetDEK returns a data key by identifier, in any state. It returns
	// [ErrDEKNotFound] for an identifier the registry does not hold.
	GetDEK(ctx context.Context, id envelope.ID) (DEKRecord, error)

	// AdvanceDEK installs next as the current data key for purpose and
	// subject if the current epoch is still from (zero when there is none),
	// and marks the previous one decrypt-only, atomically. If the current
	// epoch is no longer from, it changes nothing and returns the record that
	// is current, so concurrent callers converge on one key.
	AdvanceDEK(ctx context.Context, purpose Purpose, subject string, from uint32, next DEKRecord) (DEKRecord, error)

	// ReserveEncryptions grants up to n more encryptions on a data key,
	// advancing its reserved high-water mark, but never past limit. It grants
	// zero when the key has no capacity left or is no longer the current
	// epoch, which tells the caller to advance.
	ReserveEncryptions(ctx context.Context, id envelope.ID, n, limit uint64) (granted uint64, err error)
}

type VerifyCheck struct {
	// Mode is "reference" or "inline".
	Mode string `json:"mode"`
	// Outcome is "ok" or one of the failure classes a metric uses; it names no
	// detail.
	Outcome string `json:"outcome"`
}

type VerifyResult struct {
	Purpose Purpose `json:"purpose"`
	// OK is true when every check passed.
	OK bool `json:"ok"`
	// Checks lists what was exercised and how each went.
	Checks []VerifyCheck `json:"checks"`
}