cek

README

cek

Opens a namespace's SQLite database encrypted at rest.

cek.SetMaster(k)                            // once, at boot, from KMS
db, err := cek.Open(ns, "treasury", dataDir) // everywhere else

The key is derived from the master and the namespace. It is not generated, not wrapped, not stored, and not rotated in place — so there is no unwrap step, no rewrap step, no per-file key material to lose, and no migration path to maintain. A database is born encrypted or it does not exist.

Losing the master loses the data. That is the property you want from encryption at rest, and the reason the master lives in KMS.

Where it sits

hanzoai/namespace	names the entity, and where its file lives
hanzoai/cek	turns the master + that name into the file's key, and opens it
hanzoai/sqlite	opens a file under a raw key; knows nothing about who owns it
hanzoai/kms	holds the master

Nothing here knows about orgs, users, billing or plugins. It knows a namespace, a subsystem, and a master key.

Documentation

Overview

Package cek opens a namespace's SQLite database encrypted at rest.

There is one way to do it:

cek.SetMaster(k)                          // once, at boot, from KMS
db, err := cek.Open(ns, "treasury", dir)   // everywhere else

The key is derived from the master and the namespace. It is not generated, not wrapped, not stored, and not rotated in place — so there is no unwrap step, no rewrap step, no per-file key material to lose, and no migration path to maintain. A database is born encrypted or it does not exist. Losing the master loses the data, which is the property you want from encryption at rest and the reason the master lives in KMS.

The master is process state because that is what it is: one key, injected at boot, for every database this process opens. Threading it through every caller would not make it less global, only harder to see.

The split of responsibilities is deliberate:

namespace  names the entity and where its file lives
cek        turns the master + that name into the file's key, and opens it
sqlite     opens a file under a raw key and knows nothing about who owns it
kms        holds the master

Nothing here knows about orgs, users, billing or plugins. It knows a namespace, a subsystem, and a master key.

Index

• Constants
• Variables
• func DeriveKey(master []byte, ns namespace.Namespace, subsystem string) ([]byte, error)
• func HasMaster() bool
• func Open(ns namespace.Namespace, subsystem, dir string) (*sql.DB, error)
• func SetDevMaster() ([]byte, error)
• func SetMaster(k []byte) error

Constants

const KeyLen = 32

KeyLen is the length of the master key and of every key derived from it.

Variables

var ErrNoMaster = errors.New("cek: no master key; call SetMaster with 32 bytes from KMS")

ErrNoMaster reports that no master key has been set, or that one of the wrong length was offered.

Open fails with it rather than falling back to an unencrypted file: a service that comes up in plaintext because a key was missing has failed silently at the only thing this package does.

Functions

func DeriveKey

func DeriveKey(master []byte, ns namespace.Namespace, subsystem string) ([]byte, error)

DeriveKey returns the key for one database: the master, bound to the namespace that owns it and the subsystem it holds.

It is a pure function of its inputs, so the same namespace and subsystem always produce the same key. A file therefore reopens after a restart with nothing persisted beside it, and two databases never share a key because the subsystem is part of the binding.

func HasMaster

func HasMaster() bool

HasMaster reports whether a master key has been installed.

func Open

func Open(ns namespace.Namespace, subsystem, dir string) (*sql.DB, error)

Open opens the encrypted database holding subsystem for ns, under dir, creating it if it does not exist. The returned handle is already keyed; callers use it as an ordinary *sql.DB.

The location comes from namespace, so a file and its durable slot are two renderings of one name and cannot drift apart.

No error returned here contains the key or a DSN holding it.

func SetDevMaster

func SetDevMaster() ([]byte, error)

SetDevMaster installs a random master for a process with no KMS — tests, and a laptop. It reports the key it generated so a caller can log that this is what happened. Nothing it writes survives the process, by construction: a new random master cannot open the previous run's files.

func SetMaster

func SetMaster(k []byte) error

SetMaster installs the master key every database of this process is keyed from. Call it once at boot, before the first Open, with the key resolved from KMS.