Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 34 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 revocation event is a key event that permanently terminates control authority over an identifier by invalidating its authoritative key-pairs. In KERI, revocation is achieved through rotation to a null key, and security relies on event ordering in the KEL rather than timestamps.
A revocation event in the KERI protocol is a specialized key event that permanently terminates control authority over an autonomic identifier (AID). Once a revocation event is recorded in the Key Event Log (KEL), the authoritative key-pairs associated with that identifier become invalid and can no longer be used to sign subsequent events or exercise control.
The fundamental purpose of revocation events is to provide a cryptographically verifiable mechanism for permanently ending the lifecycle of an identifier or its control authority. This is distinct from key rotation, which transfers control to new keys while maintaining identifier continuity.
Revocation events are defined within the broader KERI protocol specification (IETF draft-ssmith-keri) as part of the key event taxonomy. The KERI protocol distinguishes between:
When constructing a revocation event, implementations must:
kt: "0", nt: "0", bt: "0"k: [], n: [], b: []s (sequence number) and p (prior event digest)Implementations must detect revocation by checking:
if (event.kt === "0" && event.k.length === 0 &&
event.nt === "0" && event.n.length === 0) {
// This is a revocation event
// Mark identifier as revoked
// Reject any subsequent events
}
When verifying a KEL that contains a revocation event:
When an issuer identifier is revoked, implementations should:
KERI deliberately simplifies revocation semantics by treating it as a special case of rotation rather than a separate operation. In traditional PKI systems, revocation and key replacement are distinct operations, creating complexity and potential for confusion. KERI resolves this through a unified model:
Key Rotation = Key Revocation + Key Replacement
A standard rotation operation in KERI functionally combines:
For scenarios requiring bare revocation without replacement, KERI uses a special case: rotation to a null key. This approach maintains protocol consistency while providing explicit support for permanent revocation.
The revocation event concept has been part of KERI since its initial design. The protocol's approach to revocation through rotation-to-null has remained stable across versions, reflecting the fundamental design principle of minimizing protocol complexity while maintaining security properties.
Revocation events operate within KERI's layered architecture:
Layer 1: Cryptographic Primitives
Layer 2: Key Event Structure
Layer 3: Key Event Log (KEL)
Layer 4: Witness Infrastructure
Revocation Event Creation Flow:
Verification Flow:
KERI's state management for revocation follows the protocol's general principles:
Append-Only Immutability: Once a revocation event is recorded in the KEL, it cannot be removed or altered. The KEL's cryptographic chaining ensures that any attempt to modify history is detectable.
Event Ordering as Security Foundation: The temporal relationship between events is determined by their position in the KEL, not by timestamps. This design choice is critical for revocation security—an attacker cannot manipulate timestamps to reorder events and bypass revocation.
No Suspension State: KERI explicitly does not support temporary revocation or suspension. Revocation is permanent and irreversible. This design decision eliminates ambiguity and simplifies the protocol's state model.
Revocation events in KERI are encoded as rotation events with specific characteristics that signal permanent termination of control authority. The event follows the standard KERI event structure encoded in CESR.
Core Event Fields:
{
"v": "KERI10JSON00011c_",
"t": "rot",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
"i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvaUfSVPzhzS6b5CM",
"s": "3",
"p": "EULvaU6JR2nmwyZ-i0d8JZAoTNZH3fSVPzhzS6b5CMaU",
"kt": "0",
"k": [],
"nt": "0",
"n": [],
"bt": "0",
"b": [],
"c": [],
"a": []
}
Field Semantics for Revocation:
v (version): CESR version string specifying encoding formatt (type): "rot" indicating a rotation eventd (SAID): Self-addressing identifier of this eventi (identifier): The AID being revokeds (sequence number): Position in the KELp (prior): Digest of the previous event, creating backward chainingkt (key threshold): Set to "0" for revocationk (keys): Empty array indicating no current keysnt (next threshold): Set to "0" for revocationn (next keys): Empty array indicating no pre-rotated keysbt (witness threshold): Set to "0" for revocationb (witnesses): Empty array indicating no witnessesc (configuration): Empty arraya (anchors): Empty arrayCritical Revocation Indicators:
The combination of kt: "0", k: [], nt: "0", and n: [] signals that this is a revocation event. The zero thresholds and empty key arrays indicate that no keys are authorized to sign subsequent events, effectively terminating control authority.
Revocation events are encoded using CESR's composable event streaming representation, which provides:
Example CESR-encoded Revocation Event:
{"v":"KERI10JSON00011c_","t":"rot","d":"ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM","i":"EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvaUfSVPzhzS6b5CM","s":"3","p":"EULvaU6JR2nmwyZ-i0d8JZAoTNZH3fSVPzhzS6b5CMaU","kt":"0","k":[],"nt":"0","n":[],"bt":"0","b":[],"c":[],"a":[]}-AABAADaguFmWb-l1SFHK-1TrEt6Rc0jiscDVjHB0eHukfMKJTmyLsvzlZfqNZFHd_KjJDPkMzBqJBHjGVHDqH_5ECDg
The signature attachment (-AAB...) follows the event body, providing cryptographic proof that the controller authorized the revocation.
After a revocation event is published, witnesses provide receipts confirming they have observed and validated the event. These receipts are encoded as indexed signatures attached to the event.
Receipt Structure:
-FAB
EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvaUfSVPzhzS6b5CM
-AABAABqNZFHd_KjJDPkMzBqJBHjGVHDqH_5ECDgaguFmWb-l1SFHK-1TrEt6Rc0jiscDVjHB0eHukfMKJTmyLsvzlZf
The -FAB prefix is a CESR group code indicating a witness receipt attachment. Multiple witnesses provide independent receipts, creating a distributed consensus on the revocation event's validity.
Revocation Event Publication:
Revocation Event Verification:
The identifier undergoes a definitive state transition upon revocation:
Pre-Revocation State:
[key1, key2, ...]n (where n ≥ 1)[digest1, digest2, ...]m (where m ≥ 1)Post-Revocation State:
[] (empty)0[] (empty)0Irreversibility: Once an identifier enters the revoked state, it cannot transition back to an active state. No subsequent events can be validly signed because no authoritative keys exist.
Event Ordering Semantics:
KERI's security model for revocation relies on event ordering within the KEL rather than wall-clock timestamps. This design choice addresses a critical security vulnerability:
Why Timestamps Are Not Used for Security:
Timestamps can be manipulated by attackers. An attacker who compromises keys could:
By using KEL ordering instead of timestamps, KERI ensures that:
Sequence Number Monotonicity:
Each event in the KEL has a sequence number s that must be strictly monotonically increasing. For a revocation event at sequence n, all events with sequence n+1 or higher are invalid because no authoritative keys exist to sign them.
Witness Agreement:
The KAACE algorithm ensures that witnesses reach agreement on the revocation event before it is considered stable. The threshold of accountable duplicity (TOAD) determines how many witness confirmations are required.
Revocation events must provide security against several threat scenarios:
Threat 1: Compromised Key Exploitation
An attacker who compromises the current signing keys attempts to continue using the identifier after the legitimate controller has revoked it.
Mitigation: The revocation event is signed with the current keys before they are considered compromised. Once the revocation is recorded in the KEL and witnessed, the compromised keys cannot be used to create valid subsequent events because the key state shows zero authoritative keys.
Threat 2: Timestamp Manipulation
An attacker attempts to create backdated events with false timestamps to make malicious events appear to occur before revocation.
Mitigation: KERI does not use timestamps for security decisions. Event ordering is determined by position in the KEL, which is cryptographically chained and cannot be reordered without breaking the chain.
Threat 3: Witness Collusion
Malicious witnesses attempt to accept conflicting versions of the KEL, one with revocation and one without.
Mitigation: The duplicity detection mechanisms in KERI ensure that any witness providing conflicting receipts is detectable. Watchers operating in promiscuous mode provide ambient verification that exposes duplicitous behavior.
Threat 4: Revocation Denial
An attacker attempts to prevent the revocation event from being distributed to validators.
Mitigation: The distributed witness and watcher infrastructure ensures that revocation events are widely propagated. Validators can query multiple sources to obtain the authoritative KEL state.
Guarantee 1: Finality
Once a revocation event is accepted by the required threshold of witnesses and recorded in the KEL, it is final and irreversible. No mechanism exists to "undo" a revocation.
Guarantee 2: Non-Repudiation
The revocation event is signed by the controller's authoritative keys, providing cryptographic proof that the controller authorized the revocation. The controller cannot later deny having revoked the identifier.
Guarantee 3: Verifiability
Any validator can independently verify the revocation by:
Guarantee 4: Duplicity Evidence
If a controller attempts to create conflicting versions of the KEL (one with revocation, one without), this duplicity is detectable and provides evidence of malicious behavior.
Resistance to Key Compromise:
Revocation events provide a mechanism to terminate control authority even after key compromise. The pre-rotation mechanism in KERI enhances this by allowing controllers to pre-commit to rotation keys that are not exposed until needed.
Resistance to Replay Attacks:
Each event includes a sequence number and digest of the previous event, preventing replay of old events. A revocation event cannot be replayed to revoke an identifier multiple times because the sequence number would conflict with the existing KEL.
Resistance to Reordering Attacks:
The cryptographic chaining of events prevents reordering. An attacker cannot move a revocation event to a different position in the KEL without breaking the chain of digests.
Post-Quantum Considerations:
KERI's design supports post-quantum cryptographic algorithms. Revocation events can use quantum-resistant signature schemes, ensuring that revocation remains secure even against future quantum computing threats.
Core KERI Dependencies:
Revocation events depend on several foundational KERI components:
ACDC Integration:
Revocation events interact with the ACDC (Authentic Chained Data Container) credential system:
Integration with Credential Registries:
Revocation events in KELs affect credential status in public verifiable credential registries:
Integration with vLEI Ecosystem:
In the vLEI (verifiable Legal Entity Identifier) ecosystem:
Integration with DID Methods:
KERI-based DID methods (e.g., did:keri, did:webs) must handle revocation:
Challenge 1: Revocation Detection Latency
Validators may not immediately learn about revocation events due to network delays or asynchronous propagation. Implementations should:
Challenge 2: Partial KEL Availability
In some scenarios, validators may only have access to a partial KEL that does not include the revocation event. Implementations should:
Challenge 3: Revocation vs. Rotation Disambiguation
Implementations must clearly distinguish between:
Parsing logic should explicitly check for the revocation indicators (kt: "0", k: [], nt: "0", n: []) rather than assuming any rotation with empty keys is a revocation.
Challenge 4: Credential Lifecycle Management
When an issuer identifier is revoked, implementations must determine the validity of previously issued credentials. Considerations include:
KEL Verification Overhead:
Verifying a revocation event requires validating the entire KEL from inception to the revocation event. For identifiers with long KEL histories, this can be computationally expensive. Optimization strategies include:
Witness Query Optimization:
Querying multiple witnesses for KEL state can introduce latency. Implementations should:
Watcher Network Efficiency:
Watcher networks provide ambient verification but can generate significant network traffic. Implementations should:
Test Scenarios:
Implementations should include test cases for:
Interoperability Testing:
Implementations should be tested against other KERI implementations to ensure:
Revocation Planning:
Controllers should plan for revocation scenarios:
Witness Configuration:
Choose witness configurations that balance security and availability:
Monitoring and Alerting:
Implement monitoring for revocation-related events:
Revocation Policies:
Organizations should define policies for when revocation is appropriate:
Audit and Compliance:
Revocation events should be auditable:
Legal Considerations:
Revocation may have legal implications:
Revocation events in KERI provide a cryptographically secure, verifiable mechanism for permanently terminating control authority over identifiers. By treating revocation as a special case of rotation (rotation to null keys) and relying on event ordering rather than timestamps for security, KERI simplifies the revocation model while maintaining strong security properties. The protocol's design ensures that revocation is final, verifiable, and resistant to manipulation, making it suitable for high-assurance identity systems including the vLEI ecosystem and other enterprise applications.
Implementations should:
Implementations should handle revocation-related errors gracefully: