When It's Used

Rotation events are used in several critical scenarios:

• Security Hygiene: Regular key rotation to limit exposure windows for potentially compromised keys
• Key Compromise Recovery: Recovering control when current signing keys are suspected or known to be compromised
• Cryptographic Agility: Transitioning to stronger cryptographic algorithms as vulnerabilities are discovered in older ones
• Witness Configuration Changes: Updating the set of witnesses or witness thresholds
• Delegation Management: Modifying delegation relationships or custodial arrangements

Key Participants

The rotation process involves several key participants:

1. Controller: The entity that initiates and signs the rotation event using current controlling keys
2. Witnesses: Designated entities that verify, sign, and store the rotation event, providing distributed consensus
3. Validators: Any party that processes the rotation event to update their view of the identifier's key state
4. Watchers: Entities that observe and record rotation events for duplicity detection

Process Flow

The rotation process follows a well-defined sequence that maintains cryptographic integrity throughout:

Step 1: Root-of-Trust Establishment

The process begins with an existing root-of-trust in a public/private key-pair that is cryptographically bound to an identifier derived from that key-pair. This root-of-trust was established either through:

• An inception event (for the first rotation)
• A prior rotation event (for subsequent rotations)

Step 2: Pre-Rotation Commitment Verification

Before a rotation can occur, the system verifies that:

• The new keys being rotated to match the cryptographic digests committed in the prior establishment event's n (next key digest) field
• The rotation satisfies the threshold requirements from the prior event's nt (next threshold) field
• The rotation event is properly signed by keys that satisfy the prior next threshold

Step 3: Rotation Message Creation

The controller creates a rotation event message containing:

{
  "v": "KERI10JSON0000160_",
  "t": "rot",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "1",
  "p": "EEnwxEm5Bg5s5aTL...",
  "kt": "1",
  "k": ["DVcuJOOJF1IE8svqEtrSuyQjGTd2HhfAkt9y2QkUtFJI"],
  "nt": "1",
  "n": ["E-dapdcC6XR1..."],
  "bt": "2",
  "br": [],
  "ba": [],
  "a": []
}

Key fields include:

• t: Event type ("rot" for rotation)
• d: SAID of the event itself
• i: Identifier prefix
• s: Sequence number (incremented from prior event)
• p: Prior event digest (backward chaining)
• kt: Current signing threshold
• k: New current public keys
• nt: Next signing threshold
• n: Next key digests (pre-rotation commitment)
• bt: Witness threshold
• br: Witnesses to remove
• ba: Witnesses to add
• a: Anchoring seals

Step 4: Cryptographic Signing

The rotation event is signed by keys that satisfy the prior next threshold from the previous establishment event. This dual-threshold validation ensures:

• The rotation is authorized by keys committed to in the previous event
• The new key state is properly established with its own threshold
• The cryptographic chain of authority remains unbroken

Step 5: Witness Verification

Rotation messages are verified by witnesses that were designated in either the inception event or subsequent rotation events:

1. Witnesses receive the rotation event
2. Each witness validates:
   • The event structure and format
   • The prior event digest matches their records
   • The signatures satisfy the prior next threshold
   • The new keys match the pre-committed digests
3. Witnesses create and sign receipt messages
4. Receipts are returned to the controller

Step 6: Receipt Collection and KERL Formation

Upon successful witnessing:

1. Receipt messages are sent back to the identity controller performing the rotation
2. The controller maintains these receipts in a key event receipt log (KERL)
3. The KERL provides distributed consensus evidence of the rotation
4. Validators can verify the rotation by checking witness receipts

Step 7: State Transition

Once the rotation is witnessed and receipted:

• The identifier's key state transitions to the new keys
• The old keys are no longer authoritative for signing
• The new keys become the current signing keys
• The next key digests establish commitments for future rotations

Technical Requirements

Cryptographic Requirements

Pre-Rotation Commitment: The rotation event MUST reveal keys that match the cryptographic digests committed in the prior establishment event's n field. This is verified by:

digest(new_public_key) == prior_event.n[index]

Dual Threshold Validation: A valid rotation must satisfy TWO distinct thresholds:

1. Prior Next Threshold: The threshold from the most recent prior establishment event, validated against the prior next key list (the unblinded public keys from the previous event's next key digest list)

2. Current Threshold: The signing threshold of the rotation event itself, validated against the current public key list being established by this rotation

This dual-threshold mechanism ensures cryptographic continuity across rotations.

Signature Requirements: The rotation event MUST be signed by keys that satisfy the prior next threshold. For a single-signature rotation:

verify(rotation_event, signature, prior_next_key) == true

For multi-signature rotations, the number of valid signatures must meet or exceed the prior next threshold.

Hash Chaining: Each rotation event includes:

• p field: Digest of the prior event (backward chaining)
• d field: SAID of the current event (self-addressing)
• n field: Digests of next keys (forward commitment)

This creates a tamper-evident chain where any modification to prior events or unauthorized rotations becomes cryptographically detectable.

Timing Considerations

Sequence Number Monotonicity: Rotation events MUST have strictly increasing sequence numbers. The sequence number s in a rotation event must be exactly one greater than the prior establishment event's sequence number.

Witness Receipt Timing: The rotation is not considered complete until a sufficient number of witness receipts are collected. The threshold of accountable duplicity (TOAD) parameter bt specifies the minimum number of witness confirmations required.

Asynchronous Processing: KERI's architecture supports asynchronous rotation processing:

• Rotation events can be transmitted before all witness receipts are collected
• Validators may observe rotation events before witnessing is complete
• The system uses escrow mechanisms to handle out-of-order event arrival

First-Seen Policy: KERI employs a first-seen policy for rotation events. The first version of a rotation event observed by a witness or validator is considered authoritative. Any conflicting rotation at the same sequence number is evidence of duplicity.

Error Handling

Invalid Pre-Rotation: If the keys in a rotation event do not match the prior next key digests, the rotation MUST be rejected. This prevents unauthorized key rotations.

Threshold Violations: If the rotation event does not satisfy the prior next threshold, it MUST be rejected. This ensures only authorized parties can rotate keys.

Sequence Number Gaps: If a rotation event arrives with a sequence number that skips values, the event MUST be placed in escrow until the missing events arrive. This handles out-of-order delivery.

Witness Threshold Failures: If insufficient witness receipts are collected to meet the TOAD threshold, the rotation may not be considered fully established. Validators may choose to wait for additional receipts or reject the rotation based on their security policies.

Duplicity Detection: If multiple conflicting rotation events are observed at the same sequence number, this constitutes duplicity. The system MUST:

1. Record both versions in a duplicitous event log (DEL)
2. Alert validators to the duplicitous behavior
3. Allow validators to make trust decisions based on the duplicity evidence

Usage Patterns

Common Scenarios

Regular Security Rotation: Organizations should implement periodic key rotation as part of security hygiene:

1. Generate new key pair securely
2. Create rotation event with new keys
3. Sign with current keys
4. Submit to witnesses
5. Collect receipts
6. Update local key state
7. Securely destroy old private keys

Emergency Compromise Recovery: When key compromise is suspected:

1. Immediately generate new key pair in secure environment
2. Create rotation event using pre-rotated keys (if current keys compromised)
3. Rush rotation through witness network
4. Broadcast rotation to all validators
5. Monitor for duplicitous rotation attempts by attacker

Witness Configuration Update: Changing witness sets:

1. Identify new witnesses to add
2. Create rotation event with:
   - `ba`: Array of new witness AIDs to add
   - `br`: Array of existing witness AIDs to remove
   - Updated `bt`: New witness threshold
3. Coordinate with both old and new witnesses
4. Ensure smooth transition of witnessing duties

Custodial Rotation: Implementing custodial agent arrangements:

1. Generate custodian signing keys
2. Generate owner rotation keys (kept in reserve)
3. Create rotation event that:
   - Sets current keys to custodian keys
   - Sets next keys to owner rotation keys
4. Owner retains ability to rotate away from custodian

Best Practices

Pre-Rotation Key Management:

• Generate next keys in secure environment separate from current keys
• Store pre-rotated keys in cold storage or hardware security modules
• Never expose pre-rotated keys until rotation time
• Use hierarchical deterministic key derivation for key management

Threshold Configuration:

• Set kt (current threshold) based on operational security requirements
• Set nt (next threshold) to enable future rotation flexibility
• Consider using fractional weights for complex multi-signature scenarios
• Ensure thresholds are achievable with available key holders

Witness Selection:

• Choose witnesses with high availability and reliability
• Distribute witnesses across different trust domains
• Set bt (witness threshold) to balance security and availability
• Regularly audit witness performance and rotate as needed

Rotation Frequency:

• Balance security benefits against operational complexity
• Rotate more frequently for high-value identifiers
• Rotate immediately upon suspected compromise
• Coordinate rotation schedules with organizational security policies

Integration Considerations

Application Integration: Applications using KERI identifiers must:

• Monitor for rotation events in the KEL
• Update cached key state when rotations occur
• Handle rotation-in-progress states gracefully
• Implement retry logic for operations during rotation

Multi-Signature Coordination: For multi-sig identifiers:

• Coordinate rotation timing among all key holders
• Collect signatures from threshold-satisfying subset
• Use secure channels for signature collection
• Implement timeout and retry mechanisms

Delegation Hierarchies: In delegated identifier scenarios:

• Delegator must approve delegate rotations
• Rotation events include delegation seals
• Coordinate rotation timing between delegator and delegate
• Maintain delegation chain integrity

Transaction Event Log Integration: For identifiers with TELs:

• Anchor TEL events to rotation events when needed
• Ensure TEL state remains consistent across rotations
• Coordinate credential issuance/revocation with rotations
• Maintain registry state through key changes

Witness Network Coordination: When rotating witness configurations:

• Notify witnesses of pending changes
• Ensure new witnesses are operational before rotation
• Maintain overlap period for smooth transition
• Monitor witness receipt collection during transition

Recovery Procedures: Establish clear procedures for:

• Emergency rotation in case of compromise
• Recovery from lost pre-rotated keys
• Handling failed rotations
• Communicating rotation status to stakeholders

The rotation event mechanism is central to KERI's security model, enabling identifiers to maintain long-term security through regular key updates while providing robust recovery mechanisms for compromise scenarios. The pre-rotation commitment scheme ensures that even if current keys are compromised, the attacker cannot capture control of the identifier, as they lack knowledge of the pre-committed next keys.

• Cache key state to avoid reprocessing entire KEL
• Use efficient signature verification algorithms
• Implement parallel witness receipt collection
• Optimize CESR parsing for high-throughput scenarios

Security Hardening

• Store pre-rotated keys in hardware security modules when possible
• Implement rate limiting on rotation operations
• Monitor for unusual rotation patterns
• Implement multi-party approval for high-value identifiers
• Use time-locked encryption for emergency recovery keys

Testing Requirements

Comprehensive test suites should cover:

• Valid single-signature rotations
• Valid multi-signature rotations with various thresholds
• Invalid pre-rotation commitments (should fail)
• Threshold violations (should fail)
• Sequence number gaps (should escrow)
• Witness configuration changes
• Duplicity scenarios
• Recovery from various failure modes