Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 72 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
A replay attack occurs when an attacker intercepts a valid authenticated message or transaction and fraudulently retransmits it at a later time to deceive the receiver into performing unintended actions, exploiting the fact that the message itself remains cryptographically valid despite being used out of its intended temporal context.
A replay attack is a network security threat where an adversary eavesdrops on legitimate communications, captures authentic messages or transactions, and subsequently retransmits them to manipulate a system into accepting the replayed data as current and valid. The fundamental danger of replay attacks lies in their low barrier to execution: unlike attacks requiring cryptographic breaking or decryption capabilities, replay attacks succeed simply by resending entire captured messages without any need to understand or modify their contents.
The attack exploits a critical vulnerability in many authentication systems: temporal context independence. When a system validates only the cryptographic authenticity of a message (signature verification, digest matching) without verifying its temporal freshness or uniqueness, previously valid messages remain perpetually valid. An attacker who captures such a message can replay it hours, days, or even years later, and the system will accept it as legitimate because the cryptographic properties remain intact.
Key properties that make replay attacks particularly dangerous:
Replay attacks have been recognized as a fundamental security threat since the early days of network authentication protocols. The classic example involves authentication tokens or session credentials: an attacker captures a valid login sequence and replays it to gain unauthorized access without ever knowing the user's password.
Traditional mitigation approaches have included:
Challenge-Response Protocols: Interactive authentication where the server sends a unique challenge (nonce) that must be incorporated into the client's response. Since each challenge is unique and time-bound, captured responses cannot be replayed. However, this requires and multiple round-trips, creating scalability limitations.
Clock Synchronization: Servers must maintain reasonably accurate system clocks. Use NTP or similar time synchronization protocols. Document [2] specifies typical clock drift parameters of 0.01-0.1 seconds.
Acceptance Window Tuning: The window [t-d-m*l, t+d] must balance security (narrow windows prevent replay) against reliability (wide windows accommodate network latency). Typical values: drift=0.1s, latency=1s, multiple=3, yielding ~3-4 second windows.
Timezone Handling: All timestamps must use ISO 8601 format with explicit timezone information (typically UTC). Avoid local time representations that create ambiguity.
State Management: Validators must maintain the last-seen sequence number for each AID. This is typically stored in the KERI database alongside the KEL itself.
Concurrent Event Handling: In distributed systems, multiple validators may receive events concurrently. Use atomic compare-and-swap operations when updating sequence number state to prevent race conditions.
Sequence Number Exhaustion: While theoretically possible with 64-bit integers, sequence number exhaustion is not a practical concern for most applications (2^64 events would require billions of years at typical event rates).
Escrow Mechanisms: For group multi-sig scenarios requiring extended coordination timeframes, implement escrow systems that:
IPEX Integration: Use IPEX protocol workflows for credential issuance and presentation that require multi-party coordination. IPEX provides negotiation mechanisms that handle asynchronous signature collection while maintaining security properties.
UUID Generation: Use cryptographically secure random number generators for one-time use nonces. Standard UUID v4 provides sufficient entropy (122 bits).
Nonce Verification: Verifiers should track presented nonces to detect replay attempts within the same verification session, though the primary protection comes from signature binding to the nonce.
: Include contextual information (verifier identifier, presentation purpose) in signed data alongside the nonce to prevent cross-context replay attacks.
Timestamp-Based Validation: Messages include timestamps that must fall within an acceptable window relative to the receiver's clock. This approach faces challenges with clock synchronization across distributed systems and determining appropriate window sizes that balance security (narrow windows) against operational reliability (wide windows to accommodate network latency and clock drift).
Sequence Numbers: Monotonically increasing counters that prevent reuse of previous messages. The receiver maintains state tracking the last valid sequence number and rejects any message with a sequence number less than or equal to previously seen values. This requires stateful tracking and careful handling of sequence number exhaustion and rollover.
Nonces (Numbers Used Once): Unique random values included in each message that the receiver tracks to ensure no value is ever accepted twice. This requires the receiver to maintain a database of used nonces, creating storage and lookup overhead that grows over time.
In traditional PKI systems, replay attack protection often relies on certificate validity periods and Certificate Revocation Lists (CRLs) or Online Certificate Status Protocol (OCSP) for real-time validation. However, these approaches introduce dependencies on centralized infrastructure and create availability vulnerabilities.
KERI addresses replay attack protection through multiple complementary mechanisms that align with its end-verifiable, decentralized architecture:
The KEL (Key Event Log) provides inherent replay attack protection through its append-only, hash-chained structure. Each event includes:
s field): Monotonically increasing counter starting from 0 at inceptionp field): Cryptographic commitment to the prior event in the chaindt field): ISO 8601 datetime of event creationValidators reject any event with a sequence number less than or equal to previously accepted events for that AID. The hash chaining ensures that events cannot be reordered or inserted into the middle of the log without breaking cryptographic integrity. This provides structural replay attack protection at the identifier control layer.
[Document 6, 9, 29] introduce KRAM as KERI's primary mechanism for replay attack protection in non-interactive authentication scenarios. KRAM implements a timestamp-based validation approach specifically designed for KERI's architecture:
Core Mechanism: All requests from web clients must include a dt (datetime) field in the request body formatted according to ISO 8601. The server validates that this timestamp falls within an acceptable time window relative to its current system time.
Time Window Calculation [Document 2]: The acceptance window is defined as [t-d-m*l, t+d] where:
t = current time at recipientd = clock drift/skew (typically 0.01-0.1 seconds)l = average network latency (typically 1 second)m = integer multiple (typically 3)This creates a narrow time window (typically 3-4 seconds) within which messages must arrive. Messages with timestamps outside this window are rejected, preventing replay of captured messages beyond the acceptance window.
Non-Interactive Design: Unlike challenge-response protocols, KRAM requires no back-and-forth interaction. Each request is self-authenticating through its signature and timestamp, enabling path-independent end-to-end verifiability [Document 29]. This provides massive scalability advantages for high-throughput applications.
Replier-Controlled Timing [Document 6]: Critically, the datetime validation is performed relative to the replier's clock, not the querier's. This prevents attackers from manipulating timestamps to extend replay windows.
[Document 8, 67] describe BADA as providing "a degree of replay attack protection" through monotonicity mechanisms:
BADA operates within KERI's RUN (Read, Update, Nullify) model [Document 4, 5, 65], which replaces traditional CRUD operations. The RUN model's append-only nature provides inherent replay attack protection: once an event is accepted and added to the log, attempts to replay it are detected because the sequence number has already been consumed.
[Document 2] identifies a critical tension between replay attack protection and group multi-sig coordination. When multiple controllers must coordinate signatures on a single message:
Simple KRAM Limitations: The narrow 3-4 second acceptance window is impractical for groups requiring loose coordination (hours to weeks). Human signers may not be immediately available, organizational approval processes may span days, and international coordination across time zones creates natural delays.
Proposed Solutions [Document 2]:
Escrow-Based KRAM: Extends the acceptance window to accommodate signature collection timeframes while maintaining replay attack protection through escrow timeout mechanisms
IPEX Protocol Integration: The IPEX (Issuance and Presentation EXchange) protocol provides negotiation mechanisms that can handle asynchronous signature collection while maintaining security properties
Threshold Signature Schemes: Cryptographic approaches that enable signature aggregation without requiring all signers to be simultaneously available
The TEL (Transaction Event Log) extends replay attack protection to credential lifecycle management. Each TEL event is anchored to a KEL event through cryptographic seals, inheriting the KEL's replay attack protection properties. Credential issuance and revocation events include:
ri field): Links to the managing TELThis ensures that credential operations cannot be replayed or reordered without detection.
[Document 27] describes CESR Proof Signatures that provide replay attack protection for ACDC credentials through:
u field): UUID values that ensure each credential presentation is uniqueThe combination of nonces and timestamps prevents captured credential presentations from being replayed in different contexts.
Authentication Sessions: When users authenticate to web applications, captured authentication messages must not be replayable. KRAM's timestamp validation ensures that authentication requests are only valid within a narrow time window.
Credential Presentations: When presenting verifiable credentials, the presentation must be bound to the specific verification context. One-time use nonces in ACDCs prevent credential presentations from being captured and replayed to different verifiers.
Key Rotation Events: Rotation events in KELs must not be replayable, as this could enable attackers to revert an identifier to a previously compromised key state. Sequence numbers and hash chaining prevent this.
Transaction Authorization: Financial transactions or other high-value operations must not be replayable. Monotonic sequence numbers and timestamp validation ensure each transaction is processed exactly once.
End Verifiability: Replay attack protection is cryptographically verifiable by any party with access to the KEL or TEL, without requiring trust in intermediaries or real-time connectivity to validation services.
Scalability: Non-interactive authentication through KRAM eliminates the round-trip overhead of challenge-response protocols, enabling high-throughput applications.
Decentralization: No dependency on centralized time servers or nonce databases. Each validator independently verifies temporal freshness using local clock and acceptable drift parameters.
Composability: Replay attack protection mechanisms compose across layers (KEL sequence numbers, KRAM timestamps, ACDC nonces) providing defense in depth.
Clock Synchronization: KRAM's timestamp validation requires reasonably synchronized clocks between clients and servers. The acceptance window must be wide enough to accommodate clock drift and network latency but narrow enough to prevent meaningful replay windows. [Document 2] notes typical windows of 3-4 seconds.
Group Coordination Tension: Narrow replay attack protection windows conflict with the need for asynchronous signature collection in group multi-sig scenarios. [Document 2] extensively discusses this tension and proposes solutions like escrow-based KRAM and IPEX integration.
State Management: While KERI minimizes state requirements compared to traditional nonce-tracking approaches, validators must maintain the last-seen sequence number for each AID they track. This is inherent to the KEL structure rather than an additional burden.
Temporal Binding: Timestamp-based protection assumes that the temporal context of a message is security-relevant. For some applications, messages may be intentionally designed to remain valid indefinitely (e.g., long-lived authorization tokens). KERI's approach requires careful consideration of which operations require temporal binding.
Network Partitions: In scenarios where network connectivity is intermittent, strict timestamp validation may reject legitimate messages that were delayed in transit. The acceptance window parameters must be tuned to the expected network conditions.
Registration Interactions [Document 7, 10, 66]: When establishing new AIDs and authorization relationships, replay attack protection must balance security with usability. The document notes that for idempotent processes (where resubmission produces no additional effect), replay attacks may be less critical, but DDoS attacks leveraging resubmission remain a concern.
Access-Controlled Interactions [Document 10, 71]: Load balancers must implement mechanisms to drop repeated requests when resources already exist. This prevents both replay attacks and resource exhaustion attacks.
Credential Issuance [Document 2]: Group multi-sig credential issuance requires extended coordination timeframes that conflict with narrow KRAM windows. Solutions include escrow mechanisms that extend acceptance windows while maintaining security properties through timeout and cancellation mechanisms.
Zero-Trust Architectures: KRAM aligns with zero-trust principles by requiring every request to be independently authenticated without relying on session state or pre-authenticated channels. Each message carries its own temporal proof of freshness.
Timestamp Rejection: When rejecting messages due to timestamp validation failure, provide clear error messages distinguishing between:
Sequence Number Violations: Distinguish between:
Timestamp Parsing: Cache parsed timestamp objects to avoid repeated ISO 8601 parsing overhead in high-throughput scenarios.
Sequence Number Lookups: Use indexed database queries for sequence number validation. Consider in-memory caching for frequently accessed AIDs.
Batch Validation: When processing multiple events, batch sequence number validations to reduce database round-trips.
Constant-Time Comparisons: Use constant-time comparison functions when validating timestamps and sequence numbers to prevent timing side-channel attacks.
Rate Limiting: Implement rate limiting on authentication endpoints to prevent brute-force attempts to find valid replay windows.
Logging and Monitoring: Log all replay attack detection events for security monitoring and incident response. Track patterns of rejected timestamps that may indicate systematic attacks or clock synchronization issues.