Glossary: keys and rotation
Terms for content keys, container KEKs, key targets, and key rotation.
Published from docs/glossary/keys.md (GitHub)
Part of the glossary.
Blob Content-Key Bundle
The wrapped blob content key plus the derived container KEK target envelopes for the blob’s active attachment bindings. The bundle is persisted in blob content-key epoch and target rows, returned by attachment listing or bind responses, and is not embedded in committed blob encrypted bytes.
Related docs:
Container KEK
A container key-encryption key. Container KEKs deliver document and blob content keys to authorized targets without exposing plaintext content keys to the server. Each container has a current KEK epoch, and child containers may inherit through parent KEK edges.
Related docs:
Container KEK Keyring
The container’s complete predecessor KEK history sealed under the current epoch’s KEK — the snapshot read path for history-inclusive access. One decrypt yields every retained historical KEK; each entry is verified against its material-committing epoch id, and the sealed length is an exact function of the epoch number. Rewritten at every rotation by re-sealing the previous entries plus the retiring key. Distinct from the Local Keyring, which wraps a device’s root key material.
Related docs:
Container KEK Predecessor Bridge
The write-once append-only log entry a rotation stores alongside the
keyring: the retiring KEK encrypted under the new KEK,
hash-committed by the signed rotation event. Never rewritten by later rotations,
which makes the bridge log ground truth for rebuilding a damaged keyring via
GET /containers/:id/kek-log.
Related docs:
Content Key
The symmetric key used to encrypt a document update stream or blob record. It is wrapped to the current verified target set rather than stored in plaintext server-side.
Related docs:
Content-Key Bundle
The collection of wrapped content-key material for one document or blob content key epoch. A bundle must match the target hash derived from verified access state before the API or app accepts it.
Related docs:
DEK
Data-encryption key. In these docs, DEK usually means the plaintext symmetric content key for a document epoch or blob record. The server stores ciphertext and wrapped keys, not plaintext DEKs.
Related docs:
Epoch
A monotonically increasing version for access state or key material. Epochs let clients distinguish current state from historical state and reject stale, conflicting, or unsafe key reuse.
Related docs:
Key Target
One recipient target for wrapped key material: a user’s encapsulation key, a group principal key, or a container KEK. The target hash commits to the sorted derived target set.
Related docs:
Local Keyring
The SDK helper that wraps one account-root secret with a host-provided wrapping key keystore, persists a manifest through a host-provided manifest store, and derives local SQLite, blob-store, identity-persistence, or custom-purpose keys from that root.
Related docs:
Member Envelope
Encrypted key material that delivers a managed principal’s active key epoch to one direct member. Member envelopes must match the active direct membership projection and recipient key fingerprints.
Related docs:
Rekey
Advancing key material to a new epoch. Container rekeys rotate container KEKs; document or blob rekeys advance content-key material for later writes.
Related docs:
Rewrap
An additive-access operation that keeps the same plaintext content key but adds or updates wrapped key material for a changed target set. Rewrap does not by itself require re-encrypting document content.
Related docs:
Rotate
A subtractive-access operation that stops using prior plaintext key material for future writes. For documents, rotate means later writes use a fresh DEK and normally begin from a fresh encrypted baseline.
Related docs:
Rotation Baseline
A signed full-history Loro snapshot that a rotate writes under the
new epoch’s DEK, bridging old readable state to the new epoch. Its
update carries checkpointKind "rotate_baseline", checkpointPayloadKind
"full_history_snapshot", and a sourceVersionVector, all committed by its
signed write header. An unlink must carry
one whose source version vector covers the
complete committed update frontier, unless the document has no committed
updates; a link must not carry one. The first valid writer for the new epoch
becomes the canonical baseline, and normal sync can then omit older ciphertext
its declared coverage dominates. That coverage is trusted, not verified, because
the server cannot open the snapshot.
Related docs:
- document-rekey-and-audit-history.md
- document-rekey-and-audit-history.md
- document-rekey-and-audit-history.md
- document-link-and-sync-protocol.md
Target Hash
The digest of the sorted derived key target set for a document, blob, or manifest state. A submitted content-key bundle or write header must match the expected target hash before it is accepted.
Related docs: