A validator is an entity or agent that evaluates whether a given signed statement attributed to an identifier is valid at the time of its issuance by determining the current authoritativekey set from at least one key event receipt log (KERL), applying duplicity detection, and assessing whether the statement meets specific use-case requirements beyond cryptographic verification.
Related Concepts
No related concepts available
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:
Implementation Notes
Critical Implementation Requirements
KEL Processing
Sequential Event Processing: Validators MUST process events in strict sequence number order. Out-of-order events should be placed in escrow until missing events arrive. Implementations should maintain an escrow queue indexed by sequence number.
Key State Caching: For performance, implementations should cache derived key states with event-based invalidation. When a new establishment event is detected, the cached key state must be invalidated and recomputed.
Incremental Updates: For long-lived identifiers with extensive KELs, implementations should support incremental key state updates rather than reprocessing the entire KEL on each validation.
Duplicity Detection
Multi-Source Comparison: Validators should query multiple sources (witnesses, watchers) and compare KEL versions. Implementations must store the source of each KEL version to enable duplicity proof generation.
First-Seen Policy: Implementations must record the first version of each event observed and reject later conflicting versions. This requires persistent storage of first-seen events.
Duplicity Evidence Storage: When duplicity is detected, implementations should store both conflicting versions with metadata (source, timestamp) to enable proof generation and forensic analysis.
Witness Interaction
Threshold Evaluation: Implementations must correctly evaluate witness thresholds, supporting both numeric thresholds (e.g., "3 of 5") and fractional weight thresholds. The TOAD parameter defines the minimum acceptable threshold.
Parallel Queries: For performance, implementations should query multiple witnesses in parallel with appropriate timeout handling. A subset of witnesses may be slow or unresponsive.
Receipt Verification: Witness receipts must be cryptographically verified using the witness's own AID and key state. Implementations should maintain witness KELs separately from the validated identifier's KEL.
Performance Optimization
Caching Layers: Implement multi-level caching:
L1: In-memory cache for recently validated key states
L2: Persistent cache for frequently accessed KELs
L3: Distributed cache for multi-instance deployments
Asynchronous Validation: For non-blocking applications, implement asynchronous validation with callback or promise-based APIs. This allows applications to continue processing while validation completes.
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:
Early KERI (2019-2020): Initial focus on cryptographic verification with validators primarily concerned with KEL integrity
KERI 2.x (2021-2022): Introduction of Transaction Event Logs (TELs) expanded validator responsibilities to include credential status verification
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:
Validator checks credential status in TEL registries (for ACDC validation)
Validator evaluates whether the statement meets business logic requirements
Output Phase:
Validator produces a binary trust decision (valid/invalid)
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.
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:
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
Batch Validation: When validating multiple statements from the same AID, derive key state once and reuse for all statements (if timestamps are compatible).
Security Considerations
Fail-Closed Behavior: On any error or ambiguity, validators should reject the statement rather than accept it. This includes:
KEL retrieval failures
Insufficient witness confirmations
Detected duplicity
Cryptographic verification failures
Timing Attack Prevention: Use constant-time comparison operations for cryptographic values to prevent timing side-channel attacks.
Resource Limits: Implement limits on:
Maximum KEL length processed
Maximum number of witnesses queried
Timeout values for network operations
Memory usage for KEL storage
Error Handling
Detailed Logging: Implementations should log:
Validation decisions (accept/reject) with reasoning
KEL sources and versions
Witness responses and confirmations
Duplicity detection events
Performance metrics (validation time, KEL size)
Graceful Degradation: When infrastructure is unavailable:
Use cached KELs if within acceptable staleness window
Reduce witness threshold requirements if configured
Provide clear indication of reduced security guarantees
Testing Requirements
Test Vectors: Implementations should be tested against:
Valid KELs with various event sequences
Duplicitous KELs with conflicting events
KELs with out-of-order events
KELs with invalid signatures
KELs with threshold violations
Integration Testing: Test validator behavior with: