Comprehensive Explanation

validator

Protocol Definition

Core Purpose and Objectives

A validator in the KERI (Key Event Receipt Infrastructure) protocol is an entity or agent that performs comprehensive evaluation of signed statements attributed to autonomic identifiers (AIDs). The validator's primary objective is to determine whether a cryptographically signed statement can be trusted for a specific purpose by establishing the authoritative key state at the time of statement issuance and applying additional validation criteria beyond mere cryptographic verification.

The validator role is distinct from but builds upon the verifier role. While a verifier focuses exclusively on cryptographic operations (signature verification, digest validation), a validator performs broader assessment including:

• Key state establishment: Determining which keys were authoritative when a statement was signed
• Duplicity detection: Identifying conflicting versions of key event logs (KELs)
• Policy application: Assessing whether the statement meets use-case-specific requirements
• Trust determination: Making a binary trust decision based on all available evidence

Formal Specification References

The validator concept is formally defined in the KERI specification maintained by the Trust over IP Foundation. Key specification documents include:

• IETF KERI Draft: The Internet Engineering Task Force draft specification authored by Samuel Smith defines validators as entities that "determine current authoritative key set for identifier from at least one key event (receipt) log"
• ACDC Specification: The Authentic Chained Data Container specification extends validator responsibilities to include credential validation
• IPEX Protocol: The Issuance and Presentation Exchange protocol defines validator roles in credential presentation workflows

Evolution and Version History

The validator concept has evolved through KERI's development:

1. Early KERI (2019-2020): Initial focus on cryptographic verification with validators primarily concerned with KEL integrity
2. KERI 2.x (2021-2022): Introduction of Transaction Event Logs (TELs) expanded validator responsibilities to include credential status verification
3. Current Specification (2023-present): Validators now encompass comprehensive trust assessment including duplicity detection, policy enforcement, and integration with witness and watcher networks

Protocol Architecture

Layering and Component Organization

Validators operate at the trust assessment layer of the KERI protocol stack, positioned above the cryptographic verification layer but below application-specific business logic:

┌─────────────────────────────────────┐
│   Application Business Logic        │
├─────────────────────────────────────┤
│   Validator (Trust Assessment)      │ ← Validator Layer
├─────────────────────────────────────┤
│   Verifier (Cryptographic Ops)      │
├─────────────────────────────────────┤
│   KERI Event Infrastructure         │
└─────────────────────────────────────┘

The validator layer interfaces with multiple KERI infrastructure components:

• KEL/KERL Storage: Accesses key event logs and key event receipt logs to establish key state history
• Witness Network: Queries witnesses for event confirmations and receipts
• Watcher Network: Consults watchers for duplicity detection evidence
• Judge/Jury Pools: In advanced deployments, validators may delegate duplicity assessment to specialized judge components
• TEL Registries: Verifies credential issuance and revocation status through Transaction Event Logs

Data Flow and Control Flow

The validation process follows a structured data flow:

Input Phase:

1. Validator receives a signed statement (message, credential, or other data)
2. Statement includes or references an AID (the claimed signer)
3. Statement includes cryptographic signatures from the AID's keys

Key State Establishment Phase:

1. Validator retrieves the AID's KEL from available sources (direct from controller, from witnesses, from watchers)
2. Validator processes the KEL to derive the key state at the time of statement issuance
3. For transferable identifiers, this requires processing all establishment events from inception through relevant rotation events
4. For non-transferable identifiers, only the inception event is required

Verification Phase:

1. Validator acts as a verifier to cryptographically verify signatures using the established key state
2. Validator verifies cryptographic digests and structural integrity
3. Validator confirms signatures satisfy the signing threshold requirements

Duplicity Detection Phase:

1. Validator compares KELs from multiple sources (witnesses, watchers) to detect inconsistencies
2. Validator applies first-seen policies to identify potential duplicitous behavior
3. Validator assesses whether detected duplicity affects the statement being validated

Policy Application Phase:

1. Validator applies use-case-specific validation criteria
2. Validator checks credential status in TEL registries (for ACDC validation)
3. Validator evaluates whether the statement meets business logic requirements

Output Phase:

1. Validator produces a binary trust decision (valid/invalid)
2. Validator may provide detailed validation results including reasons for rejection

State Management Approach

Validators maintain several categories of state:

Cached Key States: Validators typically cache derived key states for frequently validated AIDs to improve performance. Cache invalidation occurs when:

• New establishment events are detected
• Duplicity is discovered
• Cache expiration policies trigger refresh

Duplicity Evidence: Validators maintain records of detected duplicity, including:

• Conflicting KEL versions
• Source information (which witnesses/watchers provided which versions)
• Timestamps of first observation

Validation Policies: Validators store configuration defining:

• Minimum witness confirmation thresholds
• Acceptable cryptographic algorithms
• TEL registry requirements
• Use-case-specific validation rules

Trust Decisions: Validators may cache previous validation decisions with associated metadata:

• Timestamp of validation
• Key state used for validation
• Validation outcome and reasoning

Message Formats & Encoding

Validators process KERI protocol messages encoded in CESR (Composable Event Streaming Representation). The validator does not define new message types but interprets existing KERI message structures.

Key Event Messages

Validators process all KERI key event types:

Inception Events (icp):

{
  "v": "KERI10JSON0000e6_",
  "t": "icp",
  "d": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
  "i": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
  "s": "0",
  "kt": "1",
  "k": ["DqI2cOZ06RwGNwCovYUWExmdKU983IasmUKMmZflvWdQ"],
  "n": "E7FuL3Z_KBgt_QAwuZi1lUFNC69wvyHSxnMFUsKjZHss",
  "bt": "2",
  "b": ["BFUOWBaJz-sB_6b-_u_P9W8hgBQ8Su9mAtN9cY2sVGiY"],
  "c": [],
  "a": []
}

Validators extract:

• i: Identifier prefix (must match digest of inception event for self-addressing identifiers)
• kt: Current signing threshold
• k: Current public keys
• n: Next key digest (for pre-rotation)
• bt: Witness threshold (TOAD)
• b: Witness identifiers

Rotation Events (rot):

{
  "v": "KERI10JSON0000e6_",
  "t": "rot",
  "d": "E0d8JJR2nmwyYAfSVPzhzS6b5CMZAoTNZH3ULvaU6Z-i",
  "i": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
  "s": "1",
  "p": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
  "kt": "1",
  "k": ["DZb5CMZAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS"],
  "n": "EAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS6b5CMZ",
  "bt": "2",
  "br": [],
  "ba": [],
  "a": []
}

Validators verify:

• p: Prior event digest matches actual prior event
• s: Sequence number increments correctly
• k: New keys match pre-committed digest from prior event
• Signature verification uses keys from prior event (not new keys)

Interaction Events (ixn):

{
  "v": "KERI10JSON0000a6_",
  "t": "ixn",
  "d": "E0d8JJR2nmwyYAfSVPzhzS6b5CMZAoTNZH3ULvaU6Z-i",
  "i": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
  "s": "2",
  "p": "E0d8JJR2nmwyYAfSVPzhzS6b5CMZAoTNZH3ULvaU6Z-i",
  "a": [
    {
      "i": "EQzFVaMasUf4cZZBKA0pUbRc9T8yUXRFLyM1JDASYqAA",
      "s": "0",
      "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"
    }
  ]
}

Validators process:

• a: Anchor seals referencing external data or events
• Verification that interaction events don't change key state

Receipt Messages

Validators process key event receipts from witnesses:

{
  "v": "KERI10JSON0000a6_",
  "t": "rct",
  "d": "E0d8JJR2nmwyYAfSVPzhzS6b5CMZAoTNZH3ULvaU6Z-i",
  "i": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
  "s": "1"
}

Receipts include signatures from witnesses confirming they have observed and validated the referenced event.

ACDC Credential Messages

When validating ACDC credentials, validators process:

{
  "v": "ACDC10JSON00011c_",
  "d": "EBdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM",
  "i": "did:keri:EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM",
  "ri": "did:keri:ECmRy7xMwsxUelUauaXtMxTfPAMPAI6FkekeolOjkggt",
  "s": "ED6jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A",
  "a": {
    "d": "EEveY4-9XgOcLxUderzwLIr9Bf7V_NHwY1lkFrn9y2PY",
    "i": "did:keri:EpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPMBkPre",
    "dt": "2021-06-27T21:26:21.233257+00:00",
    "LEI": "254900OPPU84GM83MG36"
  }
}

Validators verify:

• i: Issuer AID and its key state
• ri: Registry identifier for credential status
• s: Schema SAID for structural validation
• a: Attribute block integrity

Protocol Mechanics

Message Exchange Patterns

Validators participate in several message exchange patterns:

Direct Validation Pattern (Direct Mode):

1. Validator receives signed statement directly from controller
2. Validator requests KEL from controller
3. Controller provides KEL
4. Validator verifies and validates

Witnessed Validation Pattern (Indirect Mode):

1. Validator receives signed statement
2. Validator queries witnesses for KEL and receipts
3. Witnesses provide KEL with their receipts
4. Validator verifies witness signatures on receipts
5. Validator assesses if sufficient witnesses confirm events
6. Validator validates statement

Watcher-Enhanced Validation Pattern:

1. Validator receives signed statement
2. Validator queries watchers for KEL copies
3. Watchers provide their observed KEL versions
4. Validator compares KEL versions for duplicity
5. If consistent, validator proceeds with validation
6. If inconsistent, validator flags duplicity and may reject

Judge-Delegated Validation Pattern (Advanced):

1. Validator receives signed statement
2. Validator queries judge for trust assessment
3. Judge provides evaluation of KEL integrity and duplicity status
4. Validator incorporates judge's assessment into validation decision

State Transitions

Validator state transitions follow this model:

Initial State: Validator has no knowledge of AID

KEL Acquisition State: Validator retrieves KEL from sources

• Transition trigger: Receipt of signed statement referencing unknown AID
• Actions: Query witnesses, watchers, or controller for KEL
• Exit condition: KEL obtained or timeout

Key State Derivation State: Validator processes KEL to derive key state

• Transition trigger: KEL acquisition complete
• Actions: Process events sequentially, verify signatures, compute key state
• Exit condition: Key state established or validation error detected

Duplicity Assessment State: Validator checks for conflicting KELs

• Transition trigger: Key state derived
• Actions: Compare KEL versions from multiple sources
• Exit condition: Consistency confirmed or duplicity detected

Cryptographic Verification State: Validator verifies signatures

• Transition trigger: Key state established and no duplicity detected
• Actions: Verify signatures using established keys
• Exit condition: Signatures valid or verification failure

Policy Application State: Validator applies use-case rules

• Transition trigger: Cryptographic verification successful
• Actions: Check TEL status, apply business logic
• Exit condition: All policies satisfied or policy violation detected

Terminal States:

• Valid: All checks passed, statement trusted
• Invalid: One or more checks failed, statement rejected

Timing and Ordering Requirements

Validators must respect several timing constraints:

KEL Ordering: Events must be processed in strict sequence number order. Out-of-order events are placed in escrow until missing events arrive.

Timestamp Validation: For time-sensitive statements, validators verify:

• Statement timestamp falls within acceptable window
• Key state at statement timestamp matches claimed keys
• No rotation events occurred between statement time and validation time that would invalidate the signature

Witness Confirmation Timing: Validators may require witness confirmations within a time window to ensure liveness. The TOAD parameter defines minimum witness confirmations required.

Cache Expiration: Cached key states have expiration policies:

• Short-lived for high-security applications (seconds to minutes)
• Long-lived for performance-critical applications (hours to days)
• Event-driven invalidation when new establishment events detected

Security Properties

Threat Model

Validators operate under a threat model where:

Adversarial Controllers: Controllers may attempt to:

• Create duplicitous KELs to deceive different validators
• Forge signatures using compromised keys
• Replay old valid statements in inappropriate contexts
• Claim authority they don't possess

Compromised Infrastructure: Validators must assume:

• Some witnesses may be compromised or faulty
• Network communications may be intercepted or modified
• Watchers may provide false duplicity reports
• Storage systems may be corrupted

Timing Attacks: Adversaries may:

• Delay delivery of rotation events to extend validity of compromised keys
• Race conditions between statement issuance and key rotation
• Exploit clock skew between validators

Security Guarantees

Validators provide several security guarantees:

Cryptographic Integrity: Through signature verification, validators guarantee that:

• Statements were signed by keys authorized at the time of signing
• Statement content has not been modified since signing
• Signatures are non-repudiable (controller cannot deny signing)

Duplicity Detection: Through KEL comparison, validators guarantee:

• Conflicting KEL versions are detected when multiple sources are consulted
• First-seen policies prevent acceptance of later conflicting versions
• Duplicitous behavior is provable through presentation of conflicting signed events

Key State Accuracy: Through KEL processing, validators guarantee:

• Key state derivation follows protocol rules exactly
• Pre-rotation commitments are enforced
• Threshold requirements are satisfied

Temporal Validity: Through timestamp checking, validators guarantee:

• Statements are evaluated using key state valid at statement time
• Expired or revoked credentials are rejected
• Replay attacks using old valid statements are detected

Attack Resistance

Validators resist several attack categories:

Live Key Compromise Attacks: If current signing keys are compromised:

• Validator detects if attacker attempts to rotate keys (requires pre-rotated keys)
• Validator rejects statements signed after compromise if rotation occurs
• Pre-rotation mechanism limits attacker's ability to maintain control

Dead Key Compromise Attacks: If old keys are compromised after rotation:

• Validator correctly identifies that old keys are no longer authoritative
• Validator rejects statements claiming to be signed with old keys
• KEL provides proof of when keys were rotated

Duplicity Attacks: If controller creates conflicting KELs:

• Validator detects inconsistency when consulting multiple sources
• Validator can prove duplicity by presenting conflicting signed events
• First-seen policies prevent validator from accepting later conflicting version

Witness Collusion Attacks: If subset of witnesses collude:

• Validator requires threshold of witness confirmations (TOAD)
• Validator can detect if witnesses provide conflicting receipts
• Watcher network provides independent verification

Replay Attacks: If attacker replays old valid statements:

• Validator checks statement timestamps against current time
• Validator verifies no key rotations occurred that would invalidate statement
• Nonces and sequence numbers prevent replay in many contexts

Interoperability

Dependencies on KERI/ACDC Protocols

Validators depend on several KERI ecosystem protocols:

KERI Core Protocol: Validators must implement:

• KEL processing and key state derivation
• Event signature verification
• Witness receipt validation
• Duplicity detection algorithms

CESR Encoding: Validators must parse:

• CESR-encoded primitives (keys, signatures, digests)
• CESR-encoded messages (events, receipts)
• CESR stream processing for efficient parsing

OOBI Protocol: Validators use Out-Of-Band Introductions to:

• Discover witness endpoints
• Discover watcher endpoints
• Bootstrap KEL acquisition

TEL Protocol: For credential validation, validators must:

• Query Transaction Event Logs for credential status
• Verify TEL anchoring to KELs
• Process issuance and revocation events

ACDC Protocol: For credential validation, validators must:

• Parse ACDC structure and schemas
• Verify ACDC chaining through edges
• Validate selective disclosure proofs

IPEX Protocol: For presentation validation, validators must:

• Process presentation exchange messages
• Verify presentation signatures
• Validate presentation against requests

Integration Points

Validators integrate with external systems through:

Witness Networks: Validators query witnesses via:

• HTTP/HTTPS endpoints
• Direct TCP connections
• OOBI-discovered endpoints

Watcher Networks: Validators query watchers via:

• Watcher APIs for KEL retrieval
• Duplicity report endpoints
• Subscription mechanisms for KEL updates

DID Resolvers: For did:keri identifiers, validators may:

• Resolve DIDs to KELs via DID resolution protocol
• Verify DID document integrity
• Extract witness information from DID documents

Credential Registries: Validators query registries via:

• TEL query endpoints
• Registry-specific APIs
• Blockchain or ledger interfaces (for ledger-backed registries)

Application Systems: Validators provide results to applications via:

• Synchronous validation APIs (request/response)
• Asynchronous validation services (message queues)
• Validation result caching layers

Implementation Considerations

Common Challenges

KEL Acquisition Performance: Retrieving KELs from multiple sources can be slow. Implementations should:

• Cache KELs with appropriate expiration policies
• Use parallel queries to multiple witnesses/watchers
• Implement timeout and retry logic
• Consider using watcher networks as KEL aggregators

Duplicity Detection Complexity: Comparing KELs from multiple sources requires:

• Efficient KEL comparison algorithms
• Storage of duplicity evidence
• Decision logic for handling detected duplicity
• User notification mechanisms for duplicity events

Key State Derivation Overhead: Processing long KELs can be computationally expensive. Implementations should:

• Cache derived key states
• Use incremental key state updates when new events arrive
• Optimize event processing pipelines
• Consider using key state snapshots for long KELs

Threshold Evaluation: Determining if witness thresholds are met requires:

• Tracking which witnesses have provided receipts
• Evaluating threshold logic (numeric or fractional weights)
• Handling partial witness responses
• Timeout logic for slow witnesses

Policy Configuration: Validators need flexible policy frameworks:

• Configurable validation rules per use case
• Schema-based validation for ACDCs
• Custom business logic integration
• Policy versioning and updates

Performance Considerations

Caching Strategy: Effective caching dramatically improves performance:

• Cache derived key states with event-based invalidation
• Cache witness receipts to avoid repeated queries
• Cache TEL status for credentials
• Use distributed caches for multi-instance deployments

Parallel Processing: Validators can parallelize:

• Queries to multiple witnesses/watchers
• Signature verification operations
• TEL status checks
• Independent validation steps

Incremental Validation: For long-lived identifiers:

• Store validated key state checkpoints
• Only process new events since last validation
• Use event sequence numbers to identify new events
• Maintain validation state across sessions

Resource Management: Validators must manage:

• Memory usage for KEL storage and caching
• Network bandwidth for KEL retrieval
• CPU usage for cryptographic operations
• Storage for duplicity evidence and validation logs

Security Hardening

Input Validation: Validators must rigorously validate:

• Event structure and field types
• Signature formats and lengths
• Sequence number ordering
• Digest and SAID correctness

Cryptographic Library Selection: Use well-vetted libraries:

• Prefer libraries with security audits
• Use constant-time implementations to prevent timing attacks
• Verify library versions and update regularly
• Test cryptographic operations thoroughly

Error Handling: Secure error handling requires:

• Fail-closed behavior (reject on error, don't accept)
• Detailed logging for security auditing
• Rate limiting to prevent DoS attacks
• Graceful degradation when infrastructure unavailable

Witness/Watcher Trust: Validators should:

• Configure minimum witness thresholds appropriate to risk
• Use diverse witness sets to prevent collusion
• Monitor witness behavior for anomalies
• Implement witness reputation systems

Deployment Patterns

Embedded Validators: For client applications:

• Lightweight validation libraries
• Local KEL caching
• Minimal external dependencies
• Suitable for mobile and desktop apps

Service-Based Validators: For enterprise deployments:

• Centralized validation services
• Shared KEL caches
• High-availability configurations
• API-based validation requests

Distributed Validators: For high-scale systems:

• Load-balanced validator pools
• Distributed caching layers
• Asynchronous validation queues
• Microservices architecture

Hybrid Validators: Combining approaches:

• Client-side validation for performance
• Server-side validation for security-critical operations
• Fallback mechanisms when services unavailable
• Validation result verification across layers