Comprehensive Explanation

reserve-rotation

Process Definition

Reserve rotation is a specialized application of partial rotation within the KERI protocol that enables controllers to maintain cryptographically committed keypairs in an unexposed state across multiple establishment events. This process allows a controller to designate pre-rotated keys in one establishment event while strategically choosing not to expose (unblind) those keys during the next rotation operation.

What It Accomplishes

Reserve rotation accomplishes several critical security and operational objectives:

1. Defense in Depth: By maintaining unexposed backup keys that are cryptographically committed but not revealed, controllers create multiple layers of security. If current operational keys are compromised, reserve keys remain protected and available for recovery.

2. Reduced Attack Surface: Keys that are never exposed to operational systems cannot be compromised through those systems. Reserve rotation minimizes the number of keys exposed at any given time while maintaining the ability to rotate to reserved keys when needed.

3. Flexible Key Management Strategy: Controllers can plan multi-stage key rotation strategies where different key sets serve different purposes (operational, backup, emergency recovery) without exposing all keys simultaneously.

4. Forward Security: Even if current keys are compromised, the reserved keys remain secure because they have never been exposed to potential attackers monitoring the KEL.

When It's Used

Reserve rotation is particularly valuable in several scenarios:

• High-Security Environments: Organizations requiring defense-in-depth security postures use reserve rotation to maintain emergency recovery keys in highly secure storage (such as HSMs or air-gapped systems) while operational keys reside in more accessible but potentially less secure environments.

• Long-Term Key Planning: When establishing an AID, controllers may pre-commit to multiple future key sets but only expose them as needed over time, reducing the window of vulnerability for each key set.

• Custodial Arrangements: In custodial rotation scenarios, reserve rotation enables the original controller to maintain ultimate control through unexposed rotation keys while delegating operational signing authority to a custodian.

• Regulatory Compliance: Organizations subject to key management regulations may use reserve rotation to demonstrate proper key lifecycle management with documented backup and recovery procedures.

Key Participants

The reserve rotation process involves:

1. Controller: The entity with ultimate control authority over the AID, responsible for:

   • Generating and securely storing reserved keypairs
   • Deciding which pre-rotated keys to expose during each rotation
   • Maintaining the cryptographic commitments through digests
   • Executing rotation events when reserved keys need to be activated

2. Witnesses: Witnesses in the witness pool who:

   • Verify the validity of rotation events
   • Confirm that exposed keys match previously committed digests
   • Create signed receipts of witnessed events
   • Participate in KAACE consensus

3. Validators: Any entity verifying the KEL who must:

   • Validate that rotation events satisfy both current and prior thresholds
   • Verify that unblinded keys match their committed digests
   • Accept that some pre-rotated keys may remain blinded (in reserve)

Process Flow

Initial Setup: Inception with Reserve Keys

The reserve rotation strategy begins at inception:

Step 1: Key Generation

• Controller generates multiple keypair sets:
  • Current operational keypairs (exposed in inception event)
  • First rotation keypairs (committed via digests)
  • Reserve keypairs (also committed via digests but intended to remain unexposed)

Step 2: Digest Commitment

• Controller computes cryptographic digests of all pre-rotated public keys
• These digests are included in the inception event's nxt (next keys) field
• The digests create a cryptographic commitment without revealing the actual keys

Step 3: Threshold Configuration

• Controller sets the nxt threshold (next threshold) that will govern the subsequent rotation
• This threshold determines how many of the pre-rotated keys must sign the next rotation event

First Rotation: Partial Exposure

When the controller performs the first rotation after inception:

Step 4: Selective Key Exposure

• Controller decides which pre-rotated keys to expose (unblind)
• Some keys are revealed and become the new current keys
• Other keys remain blinded (in reserve) - their digests remain in the KEL but the actual keys are not revealed

Step 5: Dual Threshold Validation

The rotation event must satisfy two distinct thresholds:

1. Prior Next Threshold: The rotation must be signed by enough of the unblinded pre-rotated keys to meet the threshold specified in the prior establishment event. This proves the controller has access to the keys they previously committed to.

2. Current Threshold: The rotation event itself specifies a new current threshold for the newly established key set. This threshold will govern non-establishment events until the next rotation.

Step 6: New Pre-Rotation Commitment

• The rotation event includes a new nxt field with digests of the next set of pre-rotated keys
• This may include:
  • Digests of entirely new keypairs
  • Digests of keys that were previously in reserve (re-committing to them)
  • A combination of new and previously reserved keys

Step 7: Witness Verification

• Witnesses verify the rotation event:
  • Confirm unblinded keys match their previously committed digests
  • Validate that signatures satisfy the prior next threshold
  • Verify the cryptographic integrity of the event
• Witnesses create signed receipts and participate in KAACE consensus

Subsequent Rotations: Activating Reserve Keys

When reserve keys need to be activated:

Step 8: Reserve Key Activation Decision

The controller may activate reserve keys for several reasons:

• Operational keys are compromised or suspected of compromise
• Planned key rotation schedule requires moving to reserve keys
• Custodial arrangement is being terminated
• Security posture upgrade requires fresh operational keys

Step 9: Reserve Key Unblinding

• Previously reserved keys are now unblinded (exposed) in the rotation event
• The actual public keys are revealed and can be verified against their previously committed digests
• These keys become the new current operational keys

Step 10: Threshold Satisfaction with Reserve Keys

• The rotation must be signed by the reserve keys being activated
• Signatures must satisfy the prior next threshold
• This proves the controller has maintained secure custody of the reserve keys

Step 11: New Reserve Establishment

• The rotation event commits to a new set of reserve keys via digests
• The cycle continues with new keys held in reserve for future rotations

State Changes Throughout the Process

The key state evolves through reserve rotation:

Initial State (Post-Inception):

• Current keys: Operational keypairs (exposed)
• Next keys: Digests of pre-rotated keys (some intended for reserve)
• Reserve keys: Subset of next keys intended to remain unexposed

State After First Rotation:

• Current keys: Subset of previously pre-rotated keys (now exposed)
• Next keys: New digests (may include re-committed reserve keys)
• Reserve keys: Keys from previous next set that were not exposed + new reserve keys

State After Reserve Activation:

• Current keys: Previously reserved keys (now exposed and operational)
• Next keys: New digests for future rotations
• Reserve keys: New set of unexposed keys for future contingencies

Decision Points

Controllers face several critical decision points:

1. How many keys to hold in reserve? More reserve keys provide greater flexibility but increase key management complexity.

2. When to expose reserve keys? Balance between security (keeping keys unexposed) and operational needs (having keys available for use).

3. How to structure thresholds? Higher thresholds provide greater security but require more keys to be exposed and managed.

4. Whether to re-commit to unexposed reserve keys? Keys can remain in reserve across multiple rotations by re-including their digests in subsequent nxt fields.

Technical Requirements

Cryptographic Requirements

Digest Algorithm Consistency

All key digests within a single establishment event must use the same cryptographic hash algorithm. The derivation code prepended to each digest specifies the algorithm used (e.g., Blake3-256, SHA3-256). This ensures:

• Consistent security properties across all pre-rotated keys
• Simplified validation logic for verifiers
• Predictable digest lengths for CESR encoding

Pre-Image Resistance

The hash algorithm used for key digests must provide strong pre-image resistance, meaning:

• Given a digest, it must be computationally infeasible to find the original public key
• This property protects reserve keys from cryptanalytic attacks even though their digests are public
• KERI typically uses Blake3-256 or SHA3-256, both providing 256-bit security

Signature Verification

When reserve keys are activated (unblinded):

1. The revealed public key must be hashed using the algorithm specified by its derivation code
2. The resulting digest must exactly match the previously committed digest
3. Signatures on the rotation event must verify against the revealed public keys
4. The number of valid signatures must meet or exceed the prior next threshold

Threshold Arithmetic

KERI supports both simple numeric thresholds and fractionally-weighted thresholds:

• Simple thresholds: Integer count of required signatures (e.g., "3 of 5")
• Weighted thresholds: Each key has a weight, and the sum of signing key weights must meet the threshold
• Reserve rotation must correctly handle both threshold types
• Partial exposure must ensure enough keys are unblinded to potentially satisfy the threshold

Timing Considerations

Key Generation Timing

Reserve keys should be generated:

• At inception or earlier: Ideally, all reserve keys are generated before the AID is created, allowing for secure offline key generation
• In secure environments: Key generation should occur in environments with appropriate security controls (HSMs, air-gapped systems, etc.)
• With sufficient entropy: CSPRNG must be properly seeded to ensure cryptographic strength

Rotation Event Timing

There are no protocol-enforced timing constraints on when reserve keys must be activated, but operational considerations include:

• Planned rotations: Regular rotation schedules may dictate when to move from operational to reserve keys
• Emergency rotations: Suspected compromise requires immediate activation of reserve keys
• Witness availability: Rotation events require witness participation, so timing must account for witness network availability

Key Storage Duration

Reserve keys may remain unexposed for extended periods:

• Keys must be stored securely for the entire duration they remain in reserve
• Storage systems must maintain integrity over potentially years-long timeframes
• Backup and recovery procedures must account for long-term key storage

Error Handling

Invalid Digest Matching

If an unblinded key's digest does not match the previously committed digest:

• The rotation event is invalid and must be rejected
• This indicates either:
  • Controller error (wrong key revealed)
  • Cryptographic attack attempt
  • Data corruption in the KEL
• Validators must not accept the rotation
• Witnesses must not create receipts for the invalid event

Insufficient Threshold Satisfaction

If the rotation event does not satisfy the prior next threshold:

• The rotation is invalid regardless of how many reserve keys are unblinded
• This protects against unauthorized rotation attempts
• The controller must provide additional signatures or expose additional keys

Lost Reserve Keys

If a controller loses access to reserve keys:

• If other reserve keys remain: Controller can still rotate using the remaining keys (if threshold is satisfied)
• If all reserve keys are lost: The AID may become unrecoverable unless:
  • The current operational keys remain secure
  • A new rotation can be performed using current keys to establish new reserve keys
  • This highlights the importance of secure key backup procedures

Witness Disagreement

If witnesses disagree on the validity of a reserve key activation:

• KAACE consensus algorithm resolves disagreements
• The TOAD (Threshold of Accountable Duplicity) determines how many witnesses must agree
• Duplicity detection mechanisms identify conflicting witness receipts
• Validators can make informed decisions based on witness consensus

Usage Patterns

Pattern 1: Operational-Reserve Split

Scenario: An organization wants to maintain highly secure backup keys while using more accessible keys for day-to-day operations.

Implementation:

1. At inception, generate two key sets:

   • Operational keys: Stored in enterprise key management system, accessible to authorized personnel
   • Reserve keys: Stored in HSM or offline cold storage, requiring executive authorization to access

2. Commit to both key sets in the inception event's nxt field

3. At first rotation:

   • Expose only the operational keys
   • Keep reserve keys blinded
   • Re-commit to reserve keys in the new nxt field

4. For emergency recovery:

   • Access reserve keys from secure storage
   • Perform rotation exposing reserve keys
   • Establish new operational and reserve key sets

Benefits:

• Operational keys can be rotated regularly without touching reserve keys
• Reserve keys remain protected in highest-security storage
• Clear separation of operational and emergency recovery procedures

Pattern 2: Graduated Security Levels

Scenario: A controller wants multiple tiers of reserve keys with different security levels.

Implementation:

1. Generate three key tiers:

   • Tier 1 (Current): Operational keys in standard secure storage
   • Tier 2 (First Reserve): Keys in HSM, requiring two-person authorization
   • Tier 3 (Ultimate Reserve): Keys in offline cold storage, requiring executive board authorization

2. At inception, commit to all three tiers

3. Normal rotation cycle:

   • Rotate Tier 1 keys regularly (e.g., quarterly)
   • Keep Tier 2 and Tier 3 in reserve

4. Tier 1 compromise:

   • Activate Tier 2 keys
   • Establish new Tier 1 and Tier 2 keys
   • Keep Tier 3 in reserve

5. Tier 2 compromise:

   • Activate Tier 3 keys (ultimate recovery)
   • Establish entirely new key hierarchy

Benefits:

• Multiple layers of defense
• Proportional response to different threat levels
• Clear escalation procedures

Pattern 3: Custodial with Reserve Override

Scenario: A controller delegates operational signing to a custodial agent but maintains ultimate control through reserve rotation keys.

Implementation:

1. Generate three key sets:

   • Custodial keys: Held by the custodial agent for operational signing
   • Rotation keys: Held by the controller for rotating away from custodial keys
   • Reserve keys: Held by the controller in secure storage as ultimate backup

2. Structure thresholds:

   • Current threshold: Custodial keys can sign (operational authority)
   • Next threshold: Only controller's rotation keys can rotate (rotation authority)

3. Normal operations:

   • Custodian uses custodial keys for day-to-day signing
   • Reserve keys remain unexposed

4. Terminating custodial relationship:

   • Controller uses rotation keys to perform rotation
   • Custodial keys are revoked
   • New operational keys are established
   • Reserve keys remain unexposed

5. Emergency scenario (rotation keys compromised):

   • Controller activates reserve keys
   • Performs rotation using reserve keys
   • Establishes new operational, rotation, and reserve key sets

Benefits:

• Enables secure delegation of operational authority
• Controller maintains ultimate control through rotation authority
• Reserve keys provide final layer of protection
• Controller can "fire" custodian without custodian cooperation

Best Practices

Key Generation

• Generate all reserve keys before inception when possible
• Use hardware security modules or air-gapped systems for reserve key generation
• Ensure sufficient entropy from CSPRNG
• Document key generation procedures for audit purposes

Key Storage

• Store reserve keys in physically separate locations from operational keys
• Use multiple backup copies with geographic distribution
• Implement access controls requiring multiple authorizations
• Regularly test key recovery procedures without exposing keys

Threshold Design

• Set thresholds high enough to prevent single points of failure
• Ensure enough keys are generated to satisfy thresholds even if some are lost
• Consider weighted thresholds for complex organizational structures
• Document threshold rationale for governance purposes

Rotation Planning

• Establish clear criteria for when to activate reserve keys
• Document rotation procedures for different scenarios (planned, emergency, compromise)
• Test rotation procedures in non-production environments
• Maintain rotation logs for audit and compliance

Monitoring and Auditing

• Monitor KEL for unexpected rotation events
• Audit key storage access logs regularly
• Verify witness receipts for all rotations
• Maintain documentation of all key state changes

Integration Considerations

Witness Pool Configuration

Reserve rotation requires careful witness pool design:

• Ensure sufficient witnesses to achieve TOAD threshold
• Consider geographic and organizational diversity of witnesses
• Test witness availability before performing critical rotations
• Monitor witness performance and replace underperforming witnesses

Watcher Network

Watchers provide additional security for reserve rotation:

• Watchers maintain independent copies of KELs
• Enable ambient duplicity detection
• Provide additional validation of rotation events
• Can alert controllers to unexpected rotation attempts

Agent Architecture

When using agents (such as KERIA):

• Operational keys may reside in agent keystores
• Reserve keys should be stored separately from agent infrastructure
• Agent APIs must support partial rotation operations
• Clear separation between agent-managed and controller-managed keys

Credential Issuance

Reserve rotation affects ACDC credential issuance:

• Credentials are anchored to specific key states in the KEL
• Reserve key activation creates a new key state
• Existing credentials remain valid (anchored to prior key state)
• New credentials are issued under the new key state
• TEL (Transaction Event Log) tracks credential status across rotations