Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 181 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.
Pre-rotation is a cryptographic mechanism in KERI where a controller commits to the next set of rotation keys via cryptographic in the current establishment event, enabling secure rotation even if current signing keys are compromised, providing through one-way hash functions.
Pre-rotation is KERI's foundational innovation for secure key management, representing a cryptographic commitment mechanism where each establishment event (inception or rotation) includes a digest of the next rotation keys before those keys are ever exposed or used. This forward commitment creates a verifiable chain of key authority that persists even when current signing keys are compromised.
Pre-rotation solves the fundamental vulnerability in traditional PKI systems: insecure key rotation. In conventional systems, rotation operations are signed by potentially compromised keys, creating an inherent security flaw. Pre-rotation eliminates this vulnerability by:
The mechanism assumes that private keys remain private until after issuance of the associated identifier, which is fundamental to the security model.
Pre-rotation occurs at two critical points in an AID's lifecycle:
This creates a continuous chain where each rotation simultaneously:
The pre-rotation process involves:
At identifier inception, the controller generates two sets of asymmetric key pairs:
Current Key Set: Used for immediate signing operations
k fieldNext Key Set: Reserved for future rotation
n fieldThe inception event structure includes:
{
"v": "KERI10JSON...",
"t": "icp",
"d": "<event SAID>",
"i": "<AID prefix>",
"s": "0",
"kt": "1",
"k": ["<current public key>"],
"n": ["<digest of next public key>"],
"bt": "2",
"b": ["<witness AIDs>"],
"c": [],
"a": []
}
The n field contains cryptographic digests (typically Blake3-256 or SHA3-256) of the next public keys, creating a forward blinded commitment that cannot be undone by an attacker.
Critical to pre-rotation security is the physical and logical separation of key sets:
This separation is what enables recovery from live key compromise—an attacker who compromises current signing keys cannot forge a rotation because they don't possess the pre-committed rotation keys.
When rotation is required (due to compromise, routine security hygiene, or cryptographic algorithm updates), the controller:
p field)k fieldn fieldRotation event structure:
{
"v": "KERI10JSON...",
"t": "rot",
"d": "<event SAID>",
"i": "<AID prefix>",
"s": "1",
"p": "<prior event digest>",
"kt": "1",
"k": ["<previously committed key, now revealed>"],
"n": ["<digest of new next key>"],
"bt": "2",
"b": ["<witness AIDs>"],
"br": [],
"ba": [],
"a": []
}
Validators verify rotation legitimacy by:
n field (next key digest commitment)k fieldThis verification proves the controller possessed the pre-committed keys at rotation time, establishing legitimate control authority transfer.
Witnesses validate and receipt the rotation event, providing distributed consensus on the key state change. The receipting process:
This witness-based validation provides duplicity detection—if a controller attempts conflicting rotations, witnesses will detect and report the duplicity.
Hash Function Properties:
Approved Hash Functions (128+ bits cryptographic strength):
Key Generation Requirements:
Signature Schemes:
Key Generation Timing:
Rotation Timing:
Verification Timing:
Digest Mismatch:
Missing Prior Event:
Witness Threshold Failure:
Duplicity Detection:
Scenario: Individual controller with single signing key rotating for security hygiene.
Implementation:
Best Practice: Rotate keys on regular schedule (annually, quarterly) even without compromise.
Scenario: Organization with multiple key holders requiring threshold signatures.
Implementation:
n field as arraykt (current threshold) and nt (next threshold)Best Practice: Use partial rotation to keep some keys in reserve, enabling graduated security responses.
Scenario: Controller wants to maintain backup keys that remain unexposed.
Implementation:
n field arrayBest Practice: Reserve highest-security keys for emergency recovery scenarios.
Scenario: Delegating signing authority to custodian while retaining rotation authority.
Implementation:
Best Practice: Use for enterprise scenarios where operational signing is delegated but ultimate control is retained.
Scenario: Migrating from one cryptographic algorithm to another.
Implementation:
Best Practice: Plan algorithm migrations before current algorithms are broken.
KEL Management:
Witness Coordination:
Watcher Networks:
Delegation Hierarchies:
Recovery Procedures:
Post-Quantum Security: Pre-rotation provides post-quantum security because:
Forward Security:
Duplicity Evidence:
One-Time Use:
Insufficient Key Separation:
On-Demand Key Generation:
Weak Hash Functions:
Inadequate Entropy:
Missing Witness Receipts:
Entropy Requirements: Use CSPRNG with minimum 128 bits of entropy. On Unix systems, use /dev/urandom or equivalent. Ensure proper seeding of random number generators.
Key Separation: Store current and next keys in physically separate locations with different access controls. Consider:
Key Derivation: If using hierarchical deterministic key generation, ensure proper path separation between current and next keys to prevent correlation.
Hash Function Selection: Use Blake3-256 as primary choice for performance and security. Fall back to SHA3-256 for compatibility. Avoid SHA2-256 for new implementations.
Digest Format: Digests must be CESR-encoded with appropriate derivation code:
E prefixH prefixF prefixCanonicalization: Ensure consistent serialization before hashing. Use CESR's canonical ordering for field maps.
Prior Event Reference: The p field must contain the SAID of the immediately prior establishment event. Verify hash chain integrity before accepting rotation.
Key Revelation: The k field must contain the actual public keys whose digests appeared in the prior event's n field. Order must match.
New Commitment: The n field must contain digests of newly generated next keys. These keys should already be securely stored before rotation event is published.
Threshold Validation: Both kt (current threshold) and nt (next threshold) must be validated:
Receipt Collection: Wait for TOAD threshold of witness receipts before considering rotation complete. Implement timeout and retry logic.
Witness Pool Changes: If rotating witness pool (br and ba fields), ensure:
Escrow Handling: Implement escrow for partially witnessed events. Store events awaiting sufficient receipts separately from confirmed events.
KEL Replay: To verify rotation at any point in time:
Caching Strategy: Cache verified key states to avoid repeated KEL replay. Invalidate cache on new establishment events.
Duplicity Detection: Maintain first-seen records for each sequence number. If conflicting event received for same sequence number, mark as duplicitous and alert.
Digest Mismatch: If revealed key digest doesn't match commitment:
Missing Prior Event: If prior event not available:
Threshold Failure: If insufficient signatures:
Timing Attacks: Implement constant-time comparison for digest verification to prevent timing side-channels.
Key Exposure Minimization: Minimize time that next keys are in memory. Load from secure storage only when needed for rotation.
Audit Logging: Log all key generation, rotation attempts, and verification failures for security audit trail.
Backup and Recovery: Implement secure backup procedures for next keys. Consider multi-party computation or secret sharing for high-value identifiers.
Batch Verification: When verifying multiple rotations, batch digest computations for efficiency.
Parallel Processing: Witness receipt collection can be parallelized. Use async I/O for network operations.
Incremental Updates: Maintain incremental key state rather than replaying entire KEL on each verification.
Unit Tests: Test digest computation, key revelation verification, threshold validation independently.
Integration Tests: Test complete rotation workflow including witness coordination and receipt collection.
Security Tests: Test handling of invalid rotations, digest mismatches, and duplicity scenarios.
Performance Tests: Benchmark KEL replay performance with various KEL sizes (100, 1000, 10000 events).