notes: research/KERI_Reference_skinny

This data as json

path title type status classification words body
research/KERI_Reference_skinny KERI Reference (skinny)   2026-10-15: prepared for the core-group release (the private-project section, the stub lines and one unsourced claim removed); content last updated 2026-03-31 partner 2270 # KERI Reference (skinny) Last updated: 2026-03-31 A two-page summary of the KERI Suite's essential concepts, by the curator, drawn from the v1.0 specifications. Where it and a specification disagree, the specification wins. --- ## What KERI Is KERI (Key Event Receipt Infrastructure) is an identity system that provides end-to-end verifiable control of cryptographic identifiers without requiring a blockchain or certificate authority. Approved as v1.0 by ToIP Steering Committee in January 2026. Created by Samuel M. Smith. **Core thesis:** Identity has no double-spend problem, so it does not need distributed consensus. Without consensus, KERI escapes the blockchain trilemma (decentralization/security/scalability) by not entering it. --- ## Foundational Concepts ### Self-Certifying Identifiers and AIDs A self-certifying identifier (SCI) encodes a cryptographic public key so that possession of the private key proves control. No certificate authority needed. KERI extends this with Autonomic Identifiers (AIDs): identifiers that persist through key rotation via an append-only Key Event Log (KEL). **AID properties:** (1) self-contained cryptographic root of trust, (2) decentralized control via private key management, (3) universal uniqueness. "Autonomic" = self-rule: the identifier is self-managing for rotation, delegation, and recovery. ### Key Event Log (KEL) An append-only, cryptographically chained history of all key management events (inception, rotation, delegation). Bidirectionally linked: each event hashes the previous (backward chaining), and each establishment event commits to the next rotation keys (forward chaining). To verify who controls an AID, replay the KEL from inception forward. The log is the authority. **End-verifiable:** Anyone, anywhere, at any time can verify key state given access to the KEL. No registry or CA query needed. **Incremental verification:** Verifiers cache last verified state; only process new events since last check (O(delta-n), not O(n)). ### Pre-Rotation KERI's core security mechanism. At inception, the controller generates current signing keys and next (pre-rotation) keys. Only the cryptographic digests of the next keys are published; the keys themselves stay secret. On rotation, the controller reveals the pre-rotation key (must match committed hash), signs the rotation event, and commits to the next pre-rotation key. The revealed key is then discarded. **Security guarantee:** An attacker who compromises current signing keys cannot forge a rotation because the pre-rotation key cannot be derived from its hash (preimage resistance). Structural, not procedural. **Post-quantum resilience:** Pre-rotation hides future keys behind hashes. Quantum computers provide no advantage against hash inversion (Blake2/Blake3/SHA3 at 256-bit maintain 128 bits post-quantum). Controllers can rotate to post-quantum algorithms via a standard rotation event; no protocol change required. SQAR (Surprise Quantum Attack Recovery) is a concrete procedure for this. ### Transferable vs. Non-Transferable Identifiers A Hab (habitat) is the keripy controller object for an AID. A **transferable** Hab supports key rotation via pre-rotation: the AID persists through key changes, and the KEL grows with `rot` events. Transferable AIDs use an `E` prefix (SAID of inception event). A **non-transferable** Hab has no pre-rotation commitment; its signing key is fixed for life. When a non-transferable key must change, the Hab is abandoned and a new one is created. Non-transferable AIDs use a `B` prefix (basic, no inception event needed) or `N` prefix. KERI's witness infrastructure uses non-transferable AIDs; transferable AIDs are used for persistent identities that must survive key rotation. ### Interaction Events and Seal Anchors Three KEL event families: establishment events (`icp`, `rot`, `dip`, `drt`) change key state; interaction events (`ixn`) extend the hash chain without changing key state; receipt events confirm other events. An `ixn` carries an anchor seal in its `a` field pointing to external data (typically a TEL event SAID). This is how credential lifecycle events are bound to verifiable key state: a verifier checks that the `ixn` exists in the KEL, was signed under the controller's key state at that sequence number, and references the correct external event. A `SealEvent` is a data structure `{"i": "<AID>", "s": "<sequence>", "d": "<SAID>"}` placed in the `a` field of any KEL event. When placed in an inception event, seal data contributes to the AID prefix computation (the inception event's SAID). This makes inception seals irrevocable: changing them would change the AID itself. ### Dual Threshold on Rotation Every rotation event satisfies two independent thresholds: the prior-next threshold (which pre-rotated keys must participate, establishing rotation authority) and the current threshold (which keys have signing authority going forward). This dual-threshold mechanism enables clean separation of signing and rotation authority. --- ## Infrastructure Layer ### Witnesses Controller-designated nodes that receipt KEL events and provide a verifiable promulgation network. Witnesses are accountability endpoints, not trust anchors. Protection comes from witness threshold (e.g., 3-of-5 witnesses must receipt an event). Witnesses prevent equivocation: if a controller publishes conflicting events, witnesses detect it (first-seen rule). ### Watchers Validator-chosen nodes that independently monitor KELs and detect duplicity. The controller does not choose watchers; the validator does. Watchers provide the validator's independent verification layer. Roles: Juror (evaluates duplicity evidence), Jury (group evaluation), Judge (renders verdict). ### Bifurcated Architecture Controller infrastructure (witnesses) handles event promulgation; validator infrastructure (watchers) handles event confirmation. "Shared data, no shared governance." This separation means neither party trusts the other's infrastructure. ### OOBIs (Out-of-Band Introductions) Discovery mechanism: a URL pointing to a service endpoint where a KEL can be fetched. OOBIs are explicitly insecure with respect to KERI; they only bootstrap discovery. Trust comes from verifying the KEL itself. Variants: URL, well-known, reply message, blind/SOOBI, multi-OOBI, forwarding. ### KAWA (KERI Agreement Algorithm for Watchers) Provides BFT (Byzantine Fault Tolerant) guarantees for witness pool consistency. Determines when a controller's event is sufficiently promulgated to be considered authoritative. ### Superseding Recovery A delegator can issue a superseding rotation event that overrides a compromised delegated rotation. Recovery extends to the root of the delegation tree. --- ## Encoding: CESR and SAIDs ### CESR (Composable Event Streaming Representation) Self-framing, round-trippable encoding with three domains (Text, Binary, Raw) and six transformations between them. 24-bit alignment enables composability. 13 code tables. Count Codes enable hierarchical stream composition. 3-bit Tritet cold-start parsing discriminates 8 serialization types. ### SAID (Self-Addressing Identifier) A content-addressable identifier derived from a cryptographic hash of the content it identifies. Both self-referential and cryptographically bound. SAIDs make schemas immutable (the SAID of a schema changes if any field changes). JSON Schema immutability via SAIDs is the mechanism behind ACDC's type-is-schema principle. --- ## ACDC: Credentials on KERI **Authentic Chained Data Containers (ACDCs):** KERI's credential format. Key properties: **Type-is-schema:** ACDCs have no type field; the Schema section IS the type. All schemas are static (SAIDified) to prevent schema revocation and semantic malleability attacks. **Not directly signed:** ACDCs are bound to issuer key state via anchored seals (direct KEL anchor or indirect TEL anchor via Transaction Event Log). This is what enables safe key rotation without invalidating credentials. **Chained via edge section (`-e`):** The edge section links credentials together with typed operators: `I2I` (issuer-to-issuee, requires the child credential's issuer to be the parent credential's issuee), `NI2I` (non-issuer-to-issuee, no issuer/issuee relationship required), `DI2I` (delegated-issuer-to-issuee), plus NOT/AND/OR logic. Each edge entry names a target credential by SAID and schema SAID, creating typed, verifiable credential chains. **Rules section (`-r`):** Ricardian contract: machine-readable terms embedded in the credential. The rules section carries both human-readable legal/policy text and machine-enforceable structured data. Enables chain-link confidentiality (contractual protection of disclosed data) and contingent disclosure (PII commitment without revelation until trigger). **Graduated disclosure (7 mechanisms):** Compact, Metadata, Partial (leaks sibling labels), Nested Partial, Full, Selective (leaks nothing about undisclosed fields), Bulk-Issued Instance. ### TEL (Transaction Event Log) Manages credential lifecycle (issuance, revocation) separately from key management (which lives in KEL). Two-tier model: Management TEL (registry) + VC TEL (individual credentials). TEL event types: `vcp` (registry inception, creates a registry and returns a registry key `regk` as the stable identifier for all credentials under it), `vrt` (registry rotation, changes backer configuration and thresholds), `iss` (credential issuance), `rev` (credential revocation), `bis`/`brv` (backed variants that include backer signatures). Each TEL event is anchored in the controller's KEL via an `ixn` seal, binding credential state changes to verifiable key state. TEL Registrar/Observer pattern prevents forced phone-home validation. ### IPEX (Issuance and Presentation Exchange) Six-message protocol: apply/offer/agree/grant/admit/spurn. Uniform for both issuance and presentation. Proof of Issuance via issuer signature on compact SAID. Proof of Disclosure via recursive SAD expansion. --- ## Identifier Theory ### AID/LID Couplet (Zooko's Triangle Resolution) AID = secure + decentralized but not human-meaningful. LID (Legitimized Identifier) = human-meaningful but not inherently secure (e.g., LEI code). AID|LID couplet achieves all three Zooko properties. The GLEIF vLEI is a direct instantiation: AID prefix + 20-character LEI code. ### Three Trust Bases **Autonomic (cryptographic):** Security from self-certification via key pairs. Inherently decentralizable. Portable. KERI provides this. **Algorithmic:** Security from distributed consensus (blockchain). Depends on network infrastructure; less decentralized than it appears. Expensive, slow, low throughput. **Administrative:** Security from assumed trusted entities (CAs). Nebulous security characteristics. Decidedly inferior. ### Four Authorization Models Rule 1 (Persistent): signed statements valid until explicitly revoked; key rotation does not revoke. Requires VDR. ACDCs use this. Rule 2 (Ephemeral): all statements auto-revoked on key rotation. No VDR needed. Rule 3 (Hybrid): some persistent, some ephemeral. Rule 4 (Rotate Identifier): statement persists until identifier itself rotates. ### Key Management Tiers Univalent: key gen, storage, signing co-located (HSM/TEE). Bivalent: delegator and delegate key management fully isolated. No private key transfer. Multivalent: nested delegation tree. Each level can recover from compromise below. --- ## Advanced Key Management Patterns **Fractionally weighted thresholds:** Each key gets a fractional weight (e.g., 1/2, 1/3). Threshold satisfied when sum of participating weights exceeds 1. Mirrors organizational authority hierarchies. **Custodial rotation:** Custodian holds signing keys (day-to-day ops); owner holds only pre-rotation keys (governance). Compromised custodian cannot seize identifier. **Reserve rotation:** Reserve keys (low weight, offline/escrow) persist across rotations. Activate when primary keys unavailable. Combines with post-quantum keys for SQAR. **Cooperative delegation:** Both delegator and delegatee must participate. Delegatee creates inception; delegator anchors seal. Two-way cryptographic binding. Delegator can perform superseding recovery. **Group multi-sig privacy:** KEL does not reveal whether multi-sig is single-controller-multi-device or multi-controller-group. Privacy by default. **Configuration traits:** EO (Establishment Only): only establishment events, eliminates non-establishment attack vector. DND (Do Not Delegate): prevents acting as delegator. DID (Delegate Is Delegator): horizontal scaling. --- ## Privacy Architecture (SPAC Framework) **PAC Trilemma:** Privacy, Authenticity, Confidentiality cannot all be maximized simultaneously. KERI priority: security -> authenticity -> confidentiality -> privacy. **Three-party exploitation model:** Discloser (1st) -> Disclosee (2nd) -> Observer (3rd). Any 3rd-party use or unintended 2nd-party use is exploitative. **Chain-link confidentiality:** Contractual protection: each recipient must agree to confidentiality terms before receiving data. Operationalized via metadata ACDCs (pre-contractual exchange without leaking correlatable data). **XORA (XOR Accumulator):** Privacy-preserving cryptographic accumulator. Information-theoretic security. Membership proofs without revealing other members. Duplicity detection for membership claims. --- ## Deployments and demonstrations ### GLEIF vLEI Global Legal Entity Identifier Foundation. A production deployment of KERI for organizational identity. QVIs (Qualified vLEI Issuers) operate across multiple countries. The vLEI instantiates the AID|LID couplet model (KERI AID + LEI code). ### Verifiable Voice Protocol (VVP) / GSMA Open Verifiable Calling IETF Internet Draft for authenticated caller ID using KERI/ACDC. Demonstrated live at MWC Barcelona 2026. GSMA OVC (Open Verifiable Calling) project. Addresses telephone spoofing at the identity layer rather than the network layer. --- ## Design Philosophy: Minimally Sufficient Means KERI uses the minimum mechanism needed to achieve security properties. No blockchain (not needed for identity). No global consensus (not needed without double-spend). No CA (self-certification suffices). Each component exists because no weaker alternative achieves the same guarantee. **Crypto-agility:** Specific algorithms are pluggable components, not immutable dependencies. --- ## Key Terminology - **AID** -- Autonomic Identifier (self-certifying, persists through rotation) - **KEL** -- Key Event Log (append-only key management history) - **TEL** -- Transaction Event Log (credential lifecycle: issuance, revocation) - **ACDC** -- Authentic Chained Data Container (credential format) - **SAID** -- Self-Addressing Identifier (content hash) - **CESR** -- Composable Event Streaming Representation (encoding) - **OOBI** -- Out-of-Band Introduction (discovery bootstrap) - **IPEX** -- Issuance and Presentation Exchange (6-message credential protocol) - **KRAM** -- Non-interactive authentication via signed datetime - **KGQL** -- KERI Governed Query Language - **Pre-rotation** -- Committing to next rotation keys via hash digest - **SQAR** -- Surprise Quantum Attack Recovery procedure - **KAWA** -- KERI Agreement Algorithm for Watchers (BFT witness consistency) - **BADA/RUN** -- Best Available Data Acceptance / Read-Update-Nullify (no Create, no Delete) - **Hab** -- Habitat; keripy controller object for an AID (transferable or non-transferable) - **ixn** -- Interaction event; non-establishment KEL event used to anchor external data via seal - **SealEvent** -- Anchor data structure `{i, s, d}` in KEL event `a` field; irrevocable when in inception - **regk** -- Registry key; stable identifier returned by TEL `vcp` event - **Witness** -- Controller-designated receipting node - **Watcher** -- Validator-chosen monitoring node (Juror/Jury/Judge roles) - **Backer** -- Generalized term covering witnesses and registrar backers - **QVI** -- Qualified vLEI Issuer - **vLEI** -- Verifiable Legal Entity Identifier - **LID** -- Legitimized Identifier (human-meaningful, e.g., LEI code) - **AID|LID Couplet** -- Composite identifier resolving Zooko's Triangle - **Chain-link confidentiality** -- Contractual protection of disclosed data - **XORA** -- XOR Accumulator (privacy-preserving membership proofs) - **EO** -- Establishment Only (config trait: no interaction events) - **DND** -- Do Not Delegate (config trait: no delegation) - **PAC Trilemma** -- Privacy, Authenticity, Confidentiality trade-off - **Bifurcated architecture** -- Separate controller (witness) and validator (watcher) infrastructure - **Cooperative delegation** -- Dual-party delegation requiring both delegator and delegatee participation - **Graduated disclosure** -- 7 mechanisms for selective credential revelation - **Anchored signatures** -- KEL+TEL temporal binding that defeats retrograde attacks --- ## Sources The KERI, ACDC and CESR v1.0 specifications (Trust over IP), the SAID, OOBI, IPEX, PTEL and CESR-Proof drafts, Samuel M. Smith's and Daniel Hardman's papers, and GLEIF's vLEI documentation. Each is carded in the [[300-Research/310-KERISuite/INDEX|index]].

Links from other tables