Before rotation can occur, the system verifies that the keys being rotated to were properly pre-committed in the previous establishment event. The previous event's n field contains cryptographic digests of the next keys. The rotation event must reveal public keys whose digests match these commitments.

State Change: The system transitions from trusting the current key set to preparing to trust the pre-committed key set.

Step 2: Rotation Event Construction

The controller constructs a rotation event (rot) containing:

• Previous event digest (p): Links to the prior establishment event
• Sequence number (s): Incremented from the previous establishment event
• Current keys (k): The new signing keys (revealed from previous n commitments)
• Current threshold (kt): Number of signatures required from current keys
• Next key digests (n): Cryptographic commitments to the next rotation's keys
• Next threshold (nt): Threshold for the next rotation
• Witness configuration changes: Adds (wa), cuts (wr), or rotations (br) of witnesses

State Change: The event structure is created but not yet signed.

Step 3: Dual Threshold Validation

For the rotation to be valid, it must satisfy two distinct thresholds:

1. Prior next threshold: The rotation must be signed by keys that satisfy the threshold specified in the previous event's nt field. These signatures prove that the entity controlling the pre-committed keys is authorizing the rotation.

2. Current threshold: The rotation event itself must be signed by the new current keys according to the kt threshold being established. This proves control over the newly activated keys.

This dual-threshold requirement is critical for partial rotation scenarios where only a subset of pre-committed keys are exposed.

Decision Point: If either threshold is not satisfied, the rotation is invalid and must be rejected.

Step 4: Event Signing

The controller signs the rotation event with:

• Prior next keys: To satisfy the prior next threshold
• Current keys: To satisfy the current threshold being established

Signatures are attached to the event using CESR encoding, creating a complete signed rotation message.

State Change: The event transitions from unsigned to signed, becoming a complete key event message.

Step 5: Witness Receipting

The signed rotation event is transmitted to the configured witnesses. Each witness:

1. Validates the event structure and signatures
2. Checks that it satisfies both threshold requirements
3. Creates a signed receipt of the event
4. Stores the event in its copy of the KERL
5. Returns the receipt to the controller

The controller collects receipts until the TOAD (Threshold of Accountable Duplicity) is satisfied.

State Change: The rotation event transitions from unwitnessed to witnessed, achieving distributed consensus.

Step 6: KEL Appending

Once sufficient witness receipts are collected, the rotation event is appended to the KEL. This creates an immutable record of the key state transition.

State Change: The identifier's authoritative key state is officially updated. The old keys are now considered stale, and the new keys are authoritative for all subsequent operations.

Step 7: Key State Update

Validators processing the KEL update their view of the identifier's key state:

• Current keys: Updated to the keys revealed in the rotation
• Next key commitments: Updated to the new n field digests
• Witness set: Updated based on any witness configuration changes
• Sequence number: Incremented to reflect the new establishment event

State Change: All validators now recognize the new keys as authoritative for the identifier.

Technical Requirements

Cryptographic Requirements

Pre-Rotation Mechanism: KERI's security model depends on pre-rotation, where each establishment event commits to the next rotation's keys via cryptographic digests. The rotation event must reveal keys whose digests match the previous commitments. This provides:

• Forward security: Compromise of current keys doesn't compromise pre-committed keys
• Post-quantum protection: Digest-based commitments resist quantum attacks
• Duplicity detection: Attempting to rotate to different keys creates detectable inconsistency

Cryptographic Strength: All key pairs must provide approximately 128 bits of cryptographic strength. Supported algorithms include:

• Ed25519: Elliptic curve signatures
• ECDSA secp256k1: Bitcoin-compatible signatures
• Post-quantum algorithms: As they become standardized

Hash Chain Integrity: The rotation event's p field must contain the correct digest of the previous establishment event, maintaining the backward hash chain that makes the KEL tamper-evident.

Timing Considerations

Asynchronous Processing: KERI rotation is fully asynchronous. There is no requirement for:

• Simultaneous online presence of controller and validators
• Real-time witness coordination
• Immediate propagation of the rotation event

This enables rotation even when:

• The controller is intermittently connected
• Witnesses are geographically distributed
• Network partitions exist

Escrow Mechanisms: If a rotation event arrives before its predecessor, it is placed in escrow until the missing events arrive. This handles out-of-order delivery in distributed systems.

First-Seen Policy: Witnesses and watchers implement a first-seen policy where the first version of an event at a given sequence number is considered authoritative. This prevents dead attacks where an attacker tries to present an alternative rotation history.

Error Handling

Invalid Rotation Detection: Validators must reject rotations that:

• Fail to satisfy the prior next threshold
• Fail to satisfy the current threshold
• Reveal keys whose digests don't match previous commitments
• Have incorrect sequence numbers or previous event digests
• Contain malformed CESR encoding

Duplicity Detection: If a validator receives two different rotation events at the same sequence number, this indicates duplicity. The validator:

1. Stores both versions in a duplicitous event log
2. Flags the identifier as potentially compromised
3. Alerts the controller and other validators
4. Suspends trust in the identifier until the duplicity is resolved

Recovery Procedures: If current signing keys are compromised but rotation keys remain secure, the controller can execute a rotation using the pre-committed keys to regain control. This is the primary recovery mechanism in KERI.

Usage Patterns

Typical Scenarios

Scheduled Rotation: Organizations implement regular key rotation schedules (e.g., quarterly, annually) as security hygiene. The rotation process:

1. Generate new key pairs for the next rotation
2. Create rotation event revealing current pre-committed keys
3. Include digests of the newly generated keys in the n field
4. Sign with both prior next keys and new current keys
5. Distribute to witnesses and collect receipts

Compromise Recovery: When key compromise is detected:

1. Immediate rotation using pre-committed keys that remain secure
2. Witness notification to prevent acceptance of events signed with compromised keys
3. Validator alerts to check for duplicitous events
4. Post-rotation audit to verify no unauthorized events were accepted

Cryptographic Upgrade: When transitioning to stronger algorithms:

1. Generate new key pairs using the upgraded algorithm
2. Rotate to these keys using the standard rotation process
3. The n field commits to keys using the new algorithm
4. Subsequent rotations use the upgraded cryptography

Partial Rotation: For reserve rotation or custodial rotation:

1. Only expose a subset of pre-committed keys
2. Keep remaining keys in reserve (unexposed)
3. Satisfy both prior next threshold and current threshold with the exposed subset
4. Reserve keys remain available for future rotations

Best Practices

Key Generation Hygiene:

• Generate rotation keys in secure environments (HSMs, air-gapped systems)
• Use high-entropy random number generators (CSPRNG)
• Store pre-committed keys separately from current signing keys
• Implement key ceremony procedures for high-value identifiers

Threshold Configuration:

• Set kt and nt thresholds appropriate to security requirements
• For multi-sig identifiers, use M-of-N thresholds (e.g., 2-of-3, 3-of-5)
• Consider weighted thresholds for complex governance
• Plan threshold changes across multiple rotations

Witness Management:

• Maintain diverse witness sets (geographic, organizational, technical)
• Set TOAD to balance availability and security
• Use witness rotation (wr, wa, br fields) to update witness sets
• Monitor witness availability and responsiveness

Documentation and Audit:

• Maintain records of rotation events and reasons
• Document key generation and storage procedures
• Implement audit trails for rotation authorization
• Test recovery procedures regularly

Integration Considerations

Application Layer: Applications using KERI identifiers must:

• Query current key state before verifying signatures
• Process KEL updates to track rotations
• Handle key state transitions gracefully
• Implement caching with appropriate invalidation on rotation

Witness Integration: Systems acting as witnesses must:

• Validate rotation events according to KERI rules
• Store events persistently in the KERL
• Provide receipts promptly
• Implement first-seen policy consistently

Credential Systems: ACDC credentials anchored to rotating identifiers:

• Remain valid across rotations due to KEL anchoring
• Can be verified by processing the KEL to the anchor point
• Don't require re-issuance when issuer keys rotate
• Maintain cryptographic integrity through SAID-based binding

Multi-Sig Coordination: For multi-signature identifiers:

• Coordinate rotation among multiple controllers
• Collect signatures from threshold-satisfying subset
• Handle asynchronous signature collection
• Implement timeout and retry mechanisms

Security Properties

Rotation provides several critical security properties:

Forward Security: Compromise of current signing keys doesn't compromise pre-committed rotation keys, enabling recovery.

Post-Quantum Resistance: Digest-based pre-rotation commitments resist quantum attacks on the rotation process itself.

Duplicity Evidence: Any attempt to rotate to different keys creates detectable inconsistency in the KEL.

Non-Repudiation: Rotation events are cryptographically signed and witnessed, creating non-repudiable proof of key state transitions.

Identifier Persistence: Rotation enables long-term identifier persistence despite key lifecycle management needs.

Escrow Handling

When a rotation event arrives before its predecessor:

1. Place the event in out-of-order escrow indexed by sequence number
2. Continue processing other events
3. When the missing predecessor arrives, retrieve escrowed events
4. Process events in sequence order
5. Remove from escrow after successful processing

Implement escrow timeouts to prevent resource exhaustion from malicious events.

First-Seen Policy

Witnesses and watchers MUST implement first-seen policy:

1. When receiving an event at sequence number N, check if an event at N already exists
2. If yes, compare the new event to the stored event
3. If they differ, store both in the duplicitous event log and flag the identifier
4. If they match, the event is a duplicate (not duplicitous) and can be ignored
5. Never replace a first-seen event with a later-arriving alternative

This policy is critical for detecting duplicity and preventing dead attacks.

Signature Attachment Format

Rotation events require signatures from both prior next keys and current keys. Use CESR indexed signatures:

• Signatures from prior next keys prove authorization to rotate
• Signatures from current keys prove control over newly activated keys
• Each signature includes an index indicating which key signed
• For multi-sig, collect threshold-satisfying signatures from each key set

Key State Caching

Implementations should cache key state but MUST:

1. Invalidate cache when processing rotation events
2. Recompute key state by walking the KEL from inception
3. Never trust cached key state without verifying KEL integrity
4. Implement cache invalidation on KEL updates

Error Recovery

When rotation fails:

1. Insufficient signatures: Collect additional signatures and retry
2. Witness unavailability: Wait for witnesses to come online or adjust TOAD
3. Invalid pre-rotation: This indicates a protocol violation; investigate for compromise
4. Duplicity detected: Alert controller and suspend operations pending investigation

Performance Considerations

• Batch processing: Process multiple rotation events in sequence efficiently
• Parallel validation: Verify signatures in parallel when possible
• Incremental KEL processing: Maintain checkpoints to avoid full KEL replay
• Witness parallelization: Contact witnesses concurrently to collect receipts faster