Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 182 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.
In the KERI protocol ecosystem, security represents a fundamental departure from traditional identity system security models. Rather than defining security as protection through trusted intermediaries or administrative controls, KERI establishes security as an intrinsic cryptographic property where an identifier is secure with respect to an entity if and only if there exists a mechanism by which that entity can prove control over the identifier.
This definition shifts security from a perimeter-based or trust-based model to a cryptographic proof-based model. The core principle is that security should be verifiable through mathematics and cryptography alone, without requiring trust in external parties, infrastructure, or administrative processes. An identifier in KERI is considered secure when:
KERI security requires careful attention to three critical infrastructures:
Key Pair Creation and Storage: Use cryptographically secure random number generators (CSPRNGs) with at least 128 bits of entropy. Store private keys in encrypted keystores protected by strong passphrases or hardware security modules (HSMs).
Event Signing: Implement signing operations in trusted execution environments (TEEs) when possible. Ensure signing keys are never exposed to untrusted code or transmitted over networks.
Event Signature Verification: Verification must walk the KEL to determine authoritative keys at the time of signing. Implement caching carefully to avoid using stale key state.
Security depends on proper witness selection and configuration:
Pre-rotated keys require special handling:
Implement comprehensive duplicity detection:
Continuous monitoring enhances security:
KERI's security model exhibits several distinctive properties:
Cryptographic Root-of-Trust: Security derives from self-certifying identifiers where the identifier itself is cryptographically bound to the controlling key pair. This creates a primary root-of-trust that requires no external validation.
End-Verifiability: Any party can verify the security properties of an identifier by examining its KEL and validating the cryptographic signatures and hash chains. This ambient verifiability means security can be assessed "any-data, any-where, any-time by any-body."
Duplicity Evidence: Rather than preventing all attacks, KERI makes certain attacks (particularly key compromise and unauthorized rotations) evident through duplicity detection. If an attacker creates a conflicting KEL, this duplicity becomes detectable by comparing versions.
Infrastructure Independence: KERI's security does not depend on the security of any particular infrastructure (DNS, Certificate Authorities, blockchains). The protocol is designed so that intervening infrastructure is replaceable without compromising security guarantees.
KERI's security model specifically addresses:
KERI's security model does not directly address:
The Internet Protocol (IP) was designed without a native security layer, as documented in RFC 0791. This architectural decision created a fundamental vulnerability: there is no built-in mechanism for secure attribution to the source of IP packets. Anyone can forge an IP packet, and recipients cannot reliably determine authenticity without additional security overlays.
Traditional solutions to this problem have relied on administrative trust bases:
DNS/Certificate Authority Model: The dominant approach uses DNS for name resolution and Certificate Authorities (CAs) to bind domain names to public keys. However, this model suffers from:
Blockchain/Ledger Approaches: Distributed ledger technologies attempted to address centralization by using algorithmic consensus. However, these approaches:
The concept of self-certifying identifiers emerged as an alternative approach where identifiers are cryptographically derived from public keys. Early implementations included:
However, basic self-certifying identifiers faced a critical limitation: they could not support key rotation. If a private key was compromised, the identifier had to be abandoned entirely. This made them suitable only for ephemeral or low-stakes applications.
The inability to securely rotate keys while maintaining identifier persistence represented a fundamental barrier to using self-certifying identifiers for long-lived, high-stakes applications. Traditional PKI systems support key rotation but break the cryptographic binding between identifier and key during rotation, creating a vulnerability window.
KERI's innovation was recognizing that pre-rotation could solve this problem: by cryptographically committing to the next key set before the current keys are compromised, the system maintains an unbroken chain of cryptographic proof even through key rotations.
KERI introduces Autonomic Identifiers (AIDs) that combine self-certifying properties with key rotation capability. An AID is created through an inception event that establishes:
The identifier itself is derived from this inception event, creating a self-certifying root-of-trust. The derivation uses cryptographic one-way functions (typically Blake3-256 or SHA3-256) to create an identifier that is cryptographically bound to the initial key state.
Security in KERI is maintained through Key Event Logs - append-only, cryptographically-chained logs of all key management events for an identifier. Each event in the KEL:
This structure creates multiple layers of cryptographic binding:
Backward Chaining: Each event includes the hash of the previous event, making it impossible to alter history without detection.
Forward Chaining: Pre-rotation commitments bind future key states to current events, preventing unauthorized key rotations.
Signature Binding: Events are signed by current keys, proving authorization by the controller.
Witness Receipts: Witnesses provide signed receipts of events, creating distributed evidence of event ordering.
The pre-rotation mechanism is central to KERI's security model. In each establishment event (inception or rotation), the controller commits to the digest of the next key set. This commitment:
KERI's security model distinguishes between two types of consistency:
Internal Consistency: A KEL is internally consistent if:
Internal inconsistency makes a KEL unverifiable - it fails basic cryptographic checks.
External Consistency: Multiple versions of a KEL are externally consistent if they are identical. External inconsistency (different but internally valid KELs for the same identifier) represents duplicity.
KERI's innovation is making duplicity evident rather than trying to prevent it entirely. Through ambient duplicity detection:
This approach recognizes that preventing all attacks is impossible, but making attacks detectable and provable provides strong security guarantees.
KERI employs threshold structure security where overall system security exceeds the security of individual components. This is achieved through:
Witness Pools: Rather than requiring each witness to be maximally secure, KERI uses a threshold of witnesses (e.g., 3 of 5). An attacker must compromise multiple independent witnesses to create undetectable duplicity.
Multi-Signature Control: Controllers can use M-of-N signature schemes where multiple keys must sign events. This multiplies attack surfaces - an attacker must compromise multiple independent key stores.
Watcher Networks: Independent watchers monitor for duplicity, providing additional security layers without requiring trust in any single watcher.
This approach allows individually weaker components to create collectively strong security by multiplying the number of attack surfaces an adversary must overcome.
KERI implements zero-trust computing principles:
This architecture ensures that security does not depend on trusting infrastructure - only on cryptographic verification.
KERI explicitly addresses the PAC Theorem (Privacy-Authenticity-Confidentiality trilemma), which states that a system can achieve any two of these three properties at the highest level, but not all three simultaneously.
KERI's design priorities, following ToIP design goals:
This prioritization reflects the recognition that without strong authenticity, neither confidentiality nor privacy can be meaningfully assured.
Organizational Identity: GLEIF's vLEI (verifiable Legal Entity Identifier) system uses KERI to provide cryptographically secure organizational identities. Legal entities can prove their identity and authorize representatives without relying on centralized certificate authorities.
Supply Chain Security: KERI enables end-to-end verifiable supply chains where each participant can prove their identity and the authenticity of their contributions without trusting intermediaries.
Credential Issuance: ACDCs (Authentic Chained Data Containers) built on KERI provide verifiable credentials with cryptographic proof of issuer identity and credential integrity.
IoT Device Identity: KERI's lightweight cryptographic requirements make it suitable for IoT devices that need persistent, secure identities without relying on cloud services.
Cross-Border Transactions: KERI's infrastructure independence enables secure identity verification across jurisdictional boundaries without requiring mutual recognition of certificate authorities.
Portability: Identifiers can be moved between infrastructures (from one blockchain to another, from blockchain to file system, etc.) without losing security properties.
Scalability: Verification is local and cryptographic, not requiring global consensus. This enables horizontal scaling without performance degradation.
Resilience: No single point of failure. Compromise of witnesses, watchers, or infrastructure components does not compromise identifier security.
Auditability: Complete event history is cryptographically verifiable, providing transparent audit trails.
Post-Quantum Security: Pre-rotation using hash functions provides security even against quantum computing attacks on signature algorithms.
Cost Efficiency: No transaction fees for key rotations or credential issuance (unlike blockchain-based systems).
Complexity: KERI's security model is more complex than traditional PKI, requiring understanding of key event logs, pre-rotation, and duplicity detection.
Witness Coordination: Establishing and maintaining witness pools requires coordination and infrastructure, though this is simpler than running blockchain nodes.
Storage Requirements: KELs must be stored and made available, though they are typically small (kilobytes for most identifiers).
Privacy Limitations: Strong authenticity can conflict with privacy goals. KERI provides mechanisms (like one-time-use identifiers) but cannot achieve maximum privacy while maintaining maximum authenticity.
Learning Curve: Developers and users must understand new concepts (KELs, pre-rotation, witnesses) that differ from familiar PKI models.
Ecosystem Maturity: As a newer protocol, KERI has a smaller ecosystem of tools and libraries compared to established standards like X.509.
Key Management: Controllers must protect their private keys and pre-rotated keys. KERI provides the mechanism for secure rotation but cannot prevent compromise of poorly managed keys.
Witness Selection: Security depends on choosing witnesses that are independent and unlikely to collude. Witness diversity (geographic, organizational, jurisdictional) improves security.
Watcher Networks: While not required, watcher networks significantly improve duplicity detection. Organizations should consider running watchers for high-stakes identifiers.
Recovery Planning: Controllers should have procedures for rotating to pre-committed keys if current keys are compromised. This requires secure storage of next keys separate from current keys.
Threshold Configuration: Signature and witness thresholds should be set based on risk assessment. Higher thresholds provide more security but require more coordination.
Infrastructure Monitoring: While KERI doesn't depend on infrastructure security, monitoring witness and watcher availability helps ensure identifier accessibility.
KERI's security model represents a fundamental shift from trust-based to proof-based security, enabling truly decentralized, portable, and verifiable digital identities without reliance on centralized authorities or shared infrastructure.
Set thresholds based on risk assessment:
Higher thresholds provide more security but require more coordination and infrastructure.