Trust over IP Foundation Specification: The Trust over IP Foundation's KERI specification provides the canonical technical specification, currently at version 0.9 Draft status. This specification is maintained by the Technical Stack Working Group and serves as the normative reference for implementers.

KERI Whitepapers: Two comprehensive whitepapers provide theoretical foundations:

• KERI_WP.web: The original whitepaper establishing KERI's theoretical framework
• KERI_WP_2.x.web: Extended whitepaper covering advanced concepts and use cases

Related Specifications: KERI is part of a suite of specifications including:

• CESR (Composable Event Streaming Representation): Encoding specification
• ACDC (Authentic Chained Data Containers): Verifiable credential format
• OOBI (Out-Of-Band Introduction): Discovery mechanism
• IPEX (Issuance and Presentation Exchange): Credential exchange protocol

Version History and Evolution

KERI has evolved through several major phases:

Early Development (2019-2020): Initial protocol design and whitepaper publication established core concepts of self-certifying identifiers, pre-rotation, and key event logs.

IETF Standardization (2020-2021): Migration to IETF Internet Draft process for formal standardization, with multiple draft revisions incorporating community feedback.

Trust over IP Adoption (2021-2022): Governance transition to Trust over IP Foundation's Technical Stack Working Group, establishing KERI as part of the ToIP technology stack.

Production Deployment (2022-present): GLEIF's vLEI (verifiable Legal Entity Identifier) ecosystem represents the first major production deployment, validating KERI's architecture at scale.

Current Status: The protocol is at version 0.9 Draft with active implementation in multiple programming languages (Python, Rust, Go, JavaScript, Swift) and ongoing refinement based on production experience.

Protocol Architecture

Layering and Component Organization

KERI implements a hourglass architecture that serves as a trust spanning layer for the internet:

Application Layer: Applications built on KERI (credentials, supply chain, IoT, etc.) ↓ KERI Protocol Layer: Core identifier and key management protocol (the "waist") ↓ Infrastructure Layer: Witnesses, watchers, registries, and supporting services ↓ Transport Layer: HTTP, TCP, or other transport mechanisms

This architecture enables KERI to span across different platforms and applications while maintaining consistent security properties.

Core Components

The KERI ecosystem comprises several architectural components:

Controllers: Entities that manage AIDs by:

• Generating and storing key pairs
• Creating and signing key events
• Managing key event logs
• Interacting with witnesses and watchers

Witnesses: Designated entities that:

• Receive key events from controllers
• Verify event signatures and structure
• Store key event logs
• Provide signed receipts of witnessed events
• Enable distributed consensus through KAWA (KERI's Algorithm for Witness Agreement)

Watchers: Entities that:

• Monitor key event logs in "promiscuous mode"
• Detect duplicity across the network
• Provide ambient verifiability
• Enable end-verifiable trust without being designated by controllers

Judges and Juries: Advanced components for:

• Enhanced duplicity detection
• Dynamic appraisal of infrastructure security
• Graduated trust assessment based on risk levels

Registries: Transaction Event Logs (TELs) that:

• Track credential issuance and revocation state
• Anchor to KELs for verifiable provenance
• Enable registry-backed credentials

Data Flow and Control Flow

KERI's data flow follows a publish-subscribe pattern with cryptographic verification:

Identifier Creation Flow:

1. Controller generates key pairs (current and pre-rotated)
2. Controller creates inception event with configuration
3. Controller signs inception event
4. Controller publishes to designated witnesses
5. Witnesses verify, store, and receipt the event
6. Watchers observe and store for duplicity detection

Key Rotation Flow:

1. Controller creates rotation event with new keys
2. Event reveals previously pre-rotated keys
3. Event commits to new pre-rotated keys
4. Controller signs with current keys
5. Witnesses verify against pre-rotation commitment
6. Witnesses receipt the rotation
7. Watchers detect any conflicting rotations

Verification Flow:

1. Verifier obtains key event log (KEL)
2. Verifier processes events from inception forward
3. Verifier validates signatures and pre-rotation commitments
4. Verifier checks for internal consistency
5. Verifier queries witnesses for receipts
6. Verifier checks watchers for duplicity evidence
7. Verifier establishes current key state

State Management Approach

KERI uses event sourcing for state management:

Key Event Log (KEL): The KEL is an append-only, cryptographically chained log of key events. Each event contains:

• Version string
• Identifier prefix
• Sequence number
• Event type (inception, rotation, interaction)
• Previous event digest (backward chaining)
• Current keys
• Next key digest (forward chaining via pre-rotation)
• Witness configuration
• Signatures

Key State: The current authoritative state of an identifier is derived by processing the KEL from inception to the latest event. Key state includes:

• Current signing keys
• Current signing threshold
• Next key digests (pre-rotated)
• Next signing threshold
• Witness identifiers
• Witness threshold
• Configuration parameters

State Reconstruction: Any party can reconstruct key state by replaying the KEL, enabling end-verifiable trust without reliance on external state databases.

Escrow State: KERI implementations maintain escrow state for events awaiting dependencies (out-of-order events, missing signatures, etc.). This enables fully asynchronous operation.

Message Formats & Encoding

Message Types and Structure

KERI defines several core message types, all encoded using CESR:

Inception Event (icp): Establishes a new identifier

{
  "v": "KERI10JSON0000e6_",
  "t": "icp",
  "d": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "0",
  "kt": "1",
  "k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
  "nt": "1",
  "n": ["EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM"],
  "bt": "0",
  "b": [],
  "c": [],
  "a": []
}

Rotation Event (rot): Rotates keys for an identifier

{
  "v": "KERI10JSON0000e6_",
  "t": "rot",
  "d": "E8JZAoTNZH3ULvYAfSVPzhzaU6JR2nmwyZS6b5CMi0d",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "1",
  "p": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "kt": "1",
  "k": ["DZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM"],
  "nt": "1",
  "n": ["EYAfSVPzhzaU6JR2nmwyZi0d8JZAoTNZH3ULvS6b5CM"],
  "bt": "0",
  "br": [],
  "ba": [],
  "a": []
}

Interaction Event (ixn): Anchors data without changing keys

{
  "v": "KERI10JSON0000e6_",
  "t": "ixn",
  "d": "ETNZH3ULvYAfSVPzhzaU6JR2nmwyZi0d8JZS6b5CM",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "2",
  "p": "E8JZAoTNZH3ULvYAfSVPzhzaU6JR2nmwyZS6b5CMi0d",
  "a": []
}

Receipt (rct): Witness attestation of an event

{
  "v": "KERI10JSON0000e6_",
  "t": "rct",
  "d": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "i": "EpDA1n-WiBA0A8YOqnKrB-wWQYYC49i5zY_qrIZIicQg",
  "s": "0"
}

Encoding Schemes

KERI uses CESR (Composable Event Streaming Representation) for all message encoding:

Text Domain: Base64 URL-safe encoding for human-readable formats

• JSON serialization with CESR-encoded primitives
• All cryptographic material as qualified Base64 strings
• Self-framing with derivation codes

Binary Domain: Compact binary encoding for efficiency

• CBOR or MessagePack serialization
• Binary CESR encoding of primitives
• Maintains composability with text domain

Composability: CESR's key innovation is text-binary concatenation composability - any set of primitives can be converted between text and binary domains without loss.

Field Definitions and Semantics

KERI events use standardized field labels:

Common Fields:

• v: Version string (format: KERI10JSON0000e6_)
• t: Event type (icp, rot, ixn, rct, etc.)
• d: Event digest (SAID of the event)
• i: Identifier prefix (AID)
• s: Sequence number (hex-encoded)
• p: Prior event digest (backward chaining)

Key Management Fields:

• kt: Current signing threshold
• k: Current signing keys (array)
• nt: Next signing threshold
• n: Next key digests (pre-rotation commitment)

Witness Fields:

• bt: Witness threshold (TOAD)
• b: Witness identifiers (array)
• br: Witness cuts (removals)
• ba: Witness adds (additions)

Configuration Fields:

• c: Configuration traits (array of strings)
• a: Anchoring seals (array)

Delegation Fields:

• di: Delegator identifier
• da: Delegating event seal

All fields follow insertion-ordered serialization to enable reproducible SAID computation.

Protocol Mechanics

Message Exchange Patterns

KERI implements several message exchange patterns:

Direct Mode: Peer-to-peer exchange between controllers

1. Controller A creates event
2. Controller A signs event
3. Controller A transmits to Controller B
4. Controller B verifies signatures
5. Controller B validates against KEL
6. Controller B accepts or rejects

Indirect Mode: Witness-mediated exchange

1. Controller creates event
2. Controller signs event
3. Controller publishes to witnesses
4. Witnesses verify and receipt
5. Witnesses make receipts available
6. Validators query witnesses
7. Validators verify witness receipts
8. Validators establish key state

Watcher Mode: Ambient duplicity detection

1. Watchers observe all events
2. Watchers store KELs promiscuously
3. Watchers detect conflicting versions
4. Watchers provide duplicity evidence
5. Validators query watchers
6. Validators assess duplicity

State Transitions

KERI identifiers transition through defined states:

Inception State: Initial state after inception event

• Identifier established
• Initial keys active
• Next keys committed
• Witnesses configured

Rotated State: State after rotation event

• Previous keys revoked
• Pre-rotated keys now current
• New next keys committed
• Witness configuration may change

Delegated State: State for delegated identifiers

• Delegation established
• Delegator approval required
• Cooperative delegation model

Abandoned State: Terminal state

• Next key digest list empty
• No further rotations possible
• Identifier permanently non-transferable

Timing and Ordering Requirements

KERI has specific timing and ordering properties:

Monotonic Sequence Numbers: Events must have strictly increasing sequence numbers within a KEL.

Backward Chaining: Each event (except inception) must reference the digest of the immediately prior event.

Forward Chaining: Each establishment event must commit to next keys via digest.

First-Seen Policy: Witnesses and watchers record the first version of any event they observe, making duplicity evident.

Asynchronous Processing: KERI is fully asynchronous - no global ordering required across different identifiers.

Escrow Mechanism: Events may arrive out-of-order and are escrowed until dependencies are satisfied.

No Liveness Requirement: KERI does not require liveness guarantees - identifiers can be offline indefinitely.

Security Properties

Threat Model

KERI's security model addresses several threat categories:

Key Compromise Threats:

• Live Attack: Compromise of current signing keys
• Dead Attack: Compromise of keys after they've been rotated
• Pre-rotation Protection: Unexposed pre-rotated keys provide recovery mechanism

Network Threats:

• Eclipse Attack: Isolation of a node from honest network
• Mitigation: Watcher networks provide ambient duplicity detection
• Man-in-the-Middle: Interception and modification of messages
• Mitigation: End-to-end cryptographic verification

Infrastructure Threats:

• Witness Compromise: Malicious or compromised witnesses
• Mitigation: Threshold-based witness pools and duplicity detection
• DNS/BGP Hijacking: Traditional internet infrastructure attacks
• Mitigation: KERI's cryptographic root-of-trust is independent of DNS/CA

Security Guarantees

KERI provides several formal security guarantees:

Cryptographic Root-of-Trust: Identifiers are cryptographically bound to key material through one-way functions with 128+ bits of entropy.

End-Verifiability: Any party can verify control authority by processing the KEL without trusting intermediaries.

Duplicity Evidence: Conflicting key states are cryptographically evident and cannot be hidden.

Non-Repudiation: All events are signed by controlling keys, creating non-repudiable commitments.

Post-Quantum Resistance: Pre-rotation using cryptographic digests provides protection against quantum attacks on current keys.

Ambient Verifiability: Anyone, anywhere, at any time can verify any KEL ("any-data, any-where, any-time by any-body").

Attack Resistance

KERI resists specific attack vectors:

Replay Attack Protection: Sequence numbers and event digests prevent replay attacks.

Sybil Attack Resistance: Witness pools with threshold requirements resist Sybil attacks.

Collision Attack Resistance: 128-bit cryptographic strength makes collision attacks computationally infeasible.

Quantum Attack Resistance: Pre-rotation mechanism provides forward security even if current cryptography is broken.

Duplicity Detection: First-seen policy and watcher networks make duplicitous behavior evident.

Eclipse Attack Mitigation: Distributed watcher networks provide protection against network isolation.

Interoperability

Dependencies on KERI/ACDC Protocols

KERI is the foundational protocol for a suite of related specifications:

CESR Dependency: KERI requires CESR for encoding all cryptographic primitives and messages. CESR provides:

• Self-framing primitives
• Text-binary composability
• Compact encoding
• Extensible code tables

ACDC Integration: Authentic Chained Data Containers build on KERI:

• ACDC issuers and issuees are KERI AIDs
• ACDC signatures use KERI key state
• ACDC registries use KERI TELs
• ACDC chains form verifiable provenance graphs

OOBI Discovery: Out-Of-Band Introductions enable KERI discovery:

• OOBIs associate URLs with AIDs
• Discovery via internet infrastructure
• Trust via KERI verification
• Bootstrap mechanism for witness/watcher discovery

IPEX Exchange: Issuance and Presentation Exchange protocol:

• Credential issuance using KERI AIDs
• Presentation exchange with KERI signatures
• ACDC disclosure using KERI infrastructure

Integration Points

KERI provides integration points for external systems:

DID Methods: KERI can be represented as DIDs:

• did:keri: Direct representation of KERI AIDs
• did:webs: Web-based KERI identifiers with HTTPS discovery
• DID Documents derived from KEL key state

Verifiable Credentials: KERI supports W3C VC standards:

• ACDCs as VC format
• KERI AIDs as VC issuers/subjects
• KERI signatures for VC proofs

Blockchain Integration: KERI can use blockchains as backers:

• Ledger-registered witnesses
• TEL anchoring to blockchains
• Hybrid trust models

Traditional PKI: KERI can bridge to X.509:

• KERI AIDs in certificate extensions
• Certificate transparency logs as witnesses
• Migration path from traditional PKI

Implementation Considerations

Common Challenges

Implementers face several common challenges:

Asynchronous Processing: KERI's fully asynchronous nature requires careful escrow state management and event ordering logic.

Witness Coordination: Implementing KAWA (KERI's Agreement Algorithm for Witness Agreement) requires understanding Byzantine fault tolerance and threshold signatures.

Duplicity Detection: Proper duplicity detection requires maintaining multiple KEL versions and comparing them for consistency.

Key Management: Secure generation, storage, and rotation of keys requires careful attention to cryptographic best practices.

CESR Encoding: Implementing CESR correctly requires understanding self-framing, composability, and domain conversion.

Performance Considerations

KERI implementations should consider:

KEL Processing: Processing long KELs can be computationally expensive. Implementations should:

• Cache key state to avoid reprocessing
• Use incremental processing for new events
• Implement efficient signature verification

Witness Communication: Network latency to witnesses affects performance. Implementations should:

• Use parallel witness queries
• Implement timeout and retry logic
• Cache witness receipts

Storage Requirements: KELs grow over time. Implementations should:

• Use efficient storage formats
• Implement pruning strategies for old events
• Consider distributed storage for large KELs

Cryptographic Operations: Signature verification is CPU-intensive. Implementations should:

• Use hardware acceleration where available
• Batch signature verifications
• Cache verification results

Specification Compliance

Implementers must ensure compliance with:

KERI Specification: Follow the Trust over IP KERI specification for all protocol mechanics.

CESR Specification: Use CESR encoding correctly for all primitives and messages.

Cryptographic Standards: Use approved cryptographic algorithms (Ed25519, Blake3, etc.).

Version Compatibility: Support backward compatibility for 18 months after new version adoption (per vLEI governance framework).

Reference Implementations

Several reference implementations exist:

KERIpy: Python implementation, considered the reference implementation KERIox: Rust implementation KERIgo: Go implementation
KERIjs: JavaScript implementation KERIml: Swift implementation

Implementers should study these implementations for guidance on protocol mechanics and best practices.

Asynchronous Processing

Implementations should:

• Implement escrow state management for out-of-order events
• Support fully asynchronous event processing
• Handle missing dependencies gracefully
• Provide timeout and retry mechanisms

CESR Encoding

All cryptographic primitives MUST be encoded using CESR:

• Use qualified primitives with derivation codes
• Support text-binary composability
• Implement self-framing for stream parsing
• Follow CESR code tables for all primitive types

Testing and Validation

Implementations should:

• Test against reference implementations (KERIpy)
• Validate interoperability with other implementations
• Test duplicity detection scenarios
• Verify witness coordination mechanisms
• Test key rotation and pre-rotation logic

Performance Optimization

For production deployments:

• Cache key state to avoid reprocessing KELs
• Use parallel witness queries to reduce latency
• Implement efficient storage for KELs and receipts
• Use hardware acceleration for cryptographic operations
• Batch signature verifications where possible

Security Best Practices

Implementations MUST:

• Never expose private keys to network or cloud infrastructure
• Use TEE (Trusted Execution Environment) for key operations where available
• Implement MFA (Multi-Factor Authentication) for witness endorsement
• Follow principle of least privilege for key access
• Implement audit logging for all key operations

Integration Patterns

When integrating KERI:

• Use OOBI for discovery of witnesses and watchers
• Implement ACDC for verifiable credentials
• Use IPEX for credential exchange
• Consider did:keri or did:webs for DID integration
• Leverage TELs for credential registry functionality