Part V · 2 — Data and keys

draft

Protecting what moves is half the problem; protecting what rests — and the keys that protect it — is the other. The weakest link in applied cryptography is almost always key management, not the algorithm.

2.1 File encryption: kzip

kzip (engines/sdk/kzip) is the Stack's file cipher. It uses AEAD (Part II) — confidentiality and integrity together — and is gaining a recipient mode: encrypting to someone's public key (asymmetric encapsulation, Part II), so that only the private-key owner can open it. It is the hybrid pattern in miniature: asymmetric encapsulates the key, symmetric encrypts the content.

2.2 The key lifecycle

A key is born, lives, rotates, and dies. The Stack handles each phase:

The lifecycle of a key: generate, store, derive, rotate, back up

  • Generation — always from the system CSPRNG

    (Part II); never from an ordinary RNG (there is an anti-pattern guard in the SDK).

  • Storage — master keys in an HSM (PKCS#11) when possible; in its absence,

    encrypted on disk with a passphrase in a hardware key (YubiKey) + paper backup in the safe.

  • Derivation — per-deployment keys come from HKDF over the master — one

    root, many subkeys, without reusing a secret.

  • Rotation — cadence by type: TLS certificate every 90 days, Koder ID JWT

    every 6 months (with 30 days of overlap), LUKS every 5 years. The HSM root never rotates (compromising it = reprovisioning everything).

  • Backup — database keys split by Shamir 3-of-5 among custodians: I need 3

    of the 5 to reconstruct, none alone suffices.

Shamir secret sharing is the elegant idea here: a secret becomes n parts such that k of them reconstruct it and k–1 reveal nothing. Resilience without a single point of trust.

2.3 Randomness: the silent foundation

Almost every primitive depends on unpredictable randomness — keys, nonces, salts, IVs. A weak RNG breaks everything silently (the ciphertext looks secure). That is why the rule is absolute: only the system CSPRNG (getrandom`dev/urandom), never rand()` or predictable variants. The SDK exposes only the correct wrapper and bars the rest.

2.4 Multi-tenant: isolate by design

Per policies/multi-tenant-by-default.kmd, all data carries koder_user_id from the very first commit, with isolation by RLS (row-level security) or key prefix. On the cryptographic plane, this means key material and audit trails are scoped per tenant — a leak of one does not compromise the others. Backups are also encrypted (AEAD) before leaving for cold storage.

Dense reference: HSM/PKCS#11, the full rotation cadence, Shamir, and backup in 14-koder-applied. Next: Discipline and posture — what keeps all of this correct over time, and the close of the compendium.