Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 184 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.
Revocation is the process by which a credential issuer formally withdraws their attestation to the validity of a previously issued credential, making it cryptographically verifiable that the credential should no longer be trusted, typically implemented in KERI through Transaction Event Logs (TELs) that track credential state changes.
Revocation in the KERI/ACDC ecosystem represents the formal withdrawal of an issuer's attestation to the validity of a previously issued credential. Unlike traditional PKI systems where revocation often involves complex certificate revocation lists (CRLs) or Online Certificate Status Protocol (OCSP) responders, KERI implements revocation through Transaction Event Logs (TELs) that provide cryptographically verifiable, end-verifiable proof of credential state changes.
The revocation process accomplishes several critical objectives:
Revocation becomes necessary in several scenarios:
Implementers must ensure proper cryptographic anchoring between TEL revocation events and KEL events:
For issuers using witness pools:
For public credential registries:
Always Check Status: Verifiers must check credential status before accepting presentations:
// Pseudo-code for verification
const credential = parseCredential(presentation);
const registryId = credential.ri;
const credentialSaid = credential.d;
const status = await queryTEL(registryId, credentialSaid);
if (status === 'revoked') {
throw new Error('Credential has been revoked');
}
Caching Strategy: Implement appropriate caching with TTLs:
For ecosystems implementing grace periods (like vLEI's 90-day period):
For multi-sig issuers:
The revocation process involves multiple parties:
The issuer determines that a credential must be revoked based on one of the triggering conditions mentioned above. This decision may be:
The issuer creates a revocation event in the credential's Transaction Event Log (TEL). This event:
Critical Technical Detail: The revocation event itself does NOT require signatures on the credential - it's a signed statement in the TEL that references the credential's SAID.
The revocation event is anchored to the issuer's Key Event Log (KEL) through a seal:
{
"s": "3",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"
}
This seal appears in an interaction event or rotation event in the issuer's KEL, creating a cryptographic commitment to the revocation event. The KEL event is then signed by the issuer's authoritative keys, providing the security foundation.
The KEL event containing the revocation seal is sent to the issuer's designated witnesses, who:
This witness receipting provides distributed consensus on the revocation event's existence and ordering.
For public verifiable credential registries, the revocation event propagates to Registrars (also called Backers in TEL context):
The credential's state in the TEL transitions from:
Issued → Revoked
This state change is:
When a verifier receives a credential presentation, they:
ri field)Issuer Key Authority: Only the entity controlling the issuer AID's authoritative keys can create valid revocation events. This is enforced through:
SAID Integrity: The credential's SAID must match the content being revoked. Any modification to the credential would change its SAID, making revocation references invalid.
KEL-TEL Binding: The cryptographic binding between KEL and TEL is critical:
KEL Event → Contains Seal → References TEL Event → Contains Revocation
This chain must be verifiable end-to-end without trusted intermediaries.
Witness Threshold: For issuers using witness pools, revocation events must satisfy the issuer's witness threshold (typically defined by TOAD - Threshold of Accountable Duplicity).
Grace Periods: The vLEI ecosystem implements a 90-day grace period for certain revocations, creating "ghost credentials" that remain technically valid during the transition period. This addresses practical realities of credential lifecycle management.
Event Ordering: KERI uses event sequence numbers rather than timestamps for security-critical ordering. Timestamps are informational only, as they can be manipulated by attackers.
Asynchronous Propagation: Revocation events propagate asynchronously through the distributed infrastructure:
First-Seen Policy: KERI's "first-seen" policy means that once a witness or watcher observes a revocation event, it cannot be "unseen" - this prevents certain classes of attacks.
Invalid Revocation Attempts: If a revocation event fails validation (wrong keys, invalid signature, broken chain), it is rejected by witnesses and does not affect credential state.
Duplicity Detection: If an issuer attempts to create conflicting revocation events (e.g., revoking and not revoking simultaneously), KERI's duplicity detection mechanisms identify this as malicious behavior.
Recovery Mechanisms: If an issuer's keys are compromised:
Network Partitions: During network partitions, different parts of the infrastructure may have different views of credential state. KERI's eventual consistency model ensures convergence once connectivity is restored.
For high-security scenarios requiring immediate revocation:
1. Issuer creates revocation event
2. Anchors to KEL immediately
3. Broadcasts to all witnesses
4. Waits for witness threshold receipts
5. Confirms revocation to requesting party
This pattern prioritizes speed and ensures rapid propagation.
For efficiency when revoking multiple credentials:
1. Accumulate revocation events
2. Create single KEL interaction event with multiple seals
3. Anchor all revocations in one KEL event
4. Reduces KEL growth and witness load
This pattern is used when immediate revocation is not critical.
For hierarchical credential structures:
1. Delegator revokes delegation
2. Automatically invalidates all credentials issued by delegate
3. Cascading revocation through credential chains
This pattern leverages KERI's delegation mechanisms for efficient bulk revocation.
When holders request revocation of their own credentials:
1. Holder sends signed revocation request to issuer
2. Issuer verifies holder's authority (via AID control)
3. Issuer creates revocation event
4. Holder receives confirmation
This pattern respects holder autonomy while maintaining issuer authority.
Revocation Policies: Establish clear governance policies defining:
Monitoring and Alerting: Implement systems to:
Credential Lifecycle Management: Integrate revocation into broader lifecycle:
Verifier Integration: Ensure verifiers:
With IPEX Protocol: Revocation integrates with IPEX (Issuance and Presentation Exchange):
With vLEI Ecosystem: In GLEIF's vLEI implementation:
With Multi-Signature Identifiers: For multi-sig issuers:
With Delegation Hierarchies: In delegated identifier structures:
A critical distinction in KERI terminology:
Key Rotation: In KERI, "rotation" refers to changing the authoritative keys for an identifier. This is NOT the same as credential revocation.
Credential Revocation: Withdrawing attestation to credential validity. This is a separate operation from key management.
Unified Operation: KERI's design treats key rotation as a combined revoke-and-replace operation for keys, but this is distinct from credential revocation.
Null Key Revocation: For permanent key revocation without replacement, KERI uses "rotation to null key" - but again, this is about identifier keys, not credentials.
For public verifiable credential registries:
For privacy-preserving registries:
For registry infrastructure:
Non-Repudiation: Once a revocation event is witnessed and receipted, the issuer cannot deny having revoked the credential.
Duplicity Evidence: Any attempt to present conflicting revocation states (revoked to some verifiers, not revoked to others) is cryptographically detectable.
End-Verifiability: Verifiers can independently verify revocation status without trusting intermediaries, by processing the TEL and verifying KEL anchoring.
Ambient Verifiability: Anyone, anywhere, at any time can verify credential revocation status if they have access to the TEL.
Compromise Recovery: If issuer keys are compromised, KERI's pre-rotation enables recovery and re-establishment of authority, allowing legitimate revocations to be distinguished from attacker-created ones.
Revocation in KERI/ACDC systems represents a sophisticated approach to credential lifecycle management that leverages KERI's core innovations:
This architecture provides stronger security properties than traditional revocation mechanisms while maintaining the decentralized, self-sovereign principles that define the KERI ecosystem. The integration with governance frameworks like vLEI demonstrates how these technical mechanisms support real-world organizational identity requirements.
Network Failures: Implement robust retry logic:
# Pseudo-code
max_retries = 3
for attempt in range(max_retries):
try:
result = broadcast_revocation_event(event)
break
except NetworkError:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Exponential backoff
Invalid Events: Validate revocation events before broadcasting:
Batch Processing: For bulk revocations:
Asynchronous Processing: Implement async workflows:
Key Compromise: If issuer keys are compromised:
Duplicity Detection: Monitor for conflicting revocation states:
Unit Tests: Test individual components:
Integration Tests: Test end-to-end workflows:
Security Tests: Test attack scenarios: