Comprehensive Explanation

custodial-rotation

Process Definition

Custodial rotation is a sophisticated key management process in KERI that enables secure delegation of operational signing capabilities to a third-party custodian while the original controller retains ultimate authority over the AID. This is accomplished through KERI's partial rotation mechanism, which splits control authority into two distinct capabilities:

1. Signing authority: The right to sign non-establishment events and perform day-to-day operations
2. Rotation authority: The exclusive right to rotate the authoritative key pairs and change the key state

This separation is achieved through specific structuring of thresholds and key lists in establishment events, combined with KERI's pre-rotation mechanism. The custodial agent holds keys that satisfy the current signing threshold, while the original controller maintains exclusive possession of the pre-rotated keys needed to authorize any rotation event.

When It's Used

Custodial rotation is employed in scenarios where:

• Enterprise key management: Organizations need to delegate operational signing to service providers while retaining strategic control
• Wallet-as-a-Service: Cloud-based identity services manage signing operations on behalf of users
• Agent-based architectures: Custodial agents handle routine operations while controllers maintain sovereignty
• Regulatory compliance: Separation of duties requirements mandate split authority structures
• Risk mitigation: Limiting exposure of the most critical rotation keys while enabling operational flexibility

Key Participants

The custodial rotation process involves three primary roles:

1. Original Controller: The entity with ultimate authority over the AID, who retains exclusive rotation authority
2. Custodial Agent: The delegated entity granted signing authority for operational purposes
3. Witnesses: The designated entities that verify and receipt both the delegation establishment and any subsequent rotation events

Process Flow

The custodial rotation process follows a multi-phase lifecycle:

Phase 1: Initial Establishment with Split Authority

Step 1: Controller Key Generation

The original controller generates two distinct key sets:

• Current key set: Keys that will be delegated to the custodial agent for signing authority
• Next key set: Pre-rotated keys that remain under exclusive controller possession for rotation authority

The controller computes cryptographic digests of the next key set, creating blinded commitments that will be included in the inception event.

Step 2: Threshold Configuration

The controller structures the establishment event with carefully designed thresholds:

• Current threshold (kt): Set to enable the custodial agent's keys to satisfy signing requirements (e.g., "1" for single custodian, or weighted threshold for multiple custodians)
• Next threshold (nt): Set to require the controller's pre-rotated keys for rotation authorization (typically excluding custodian keys from rotation authority)

Example threshold structure:

{
  "kt": "1",  // Custodian can sign with single key
  "k": ["<custodian_public_key>"],
  "nt": "1",  // Controller must sign rotations
  "n": ["<digest_of_controller_next_key>"]
}

Step 3: Inception Event Creation

The controller creates an inception event that:

• Establishes the AID with the custodian's public key in the current key list
• Commits to the controller's next keys via digests in the next key digest list
• Sets thresholds that enable custodial signing but reserve rotation authority
• Includes configuration traits and witness designations

Step 4: Key Material Transfer

The controller securely transfers the current private keys to the custodial agent through an out-of-band secure channel. The controller retains:

• The pre-rotated private keys (never shared with custodian)
• The ability to generate additional pre-rotated keys for future rotations
• Complete KEL history for verification

Phase 2: Operational Signing by Custodian

Step 5: Custodial Signing Operations

During normal operations, the custodial agent:

• Receives signing requests from applications or services
• Creates interaction events or signs external data
• Applies signatures using the delegated current private keys
• Submits signed events to the designated witness pool
• Returns signed data to requesting parties

The custodian can perform all non-establishment operations:

• Signing ACDC credentials
• Creating interaction events with seals
• Authenticating messages and data
• Participating in IPEX exchanges

Critical Limitation: The custodian cannot create rotation events because they lack the pre-rotated private keys needed to satisfy the next threshold from the prior establishment event.

Phase 3: Controller-Initiated Rotation ("Firing" the Custodian)

Step 6: Rotation Decision

The controller decides to rotate keys, which may be triggered by:

• Termination of custodial relationship
• Suspected key compromise
• Scheduled key rotation policy
• Change in operational requirements
• Security incident or audit finding

Step 7: New Key Generation

The controller generates:

• New current key set (may be controller-held or delegated to a different custodian)
• New next key set for future rotation authority
• Digests of the new next keys

Step 8: Rotation Event Creation

The controller creates a rotation event that:

1. References prior establishment: Links to the previous event via digest
2. Exposes prior next keys: Reveals the actual public keys corresponding to the digests from the prior event (proving possession)
3. Establishes new current keys: Specifies the new current key list and threshold
4. Commits to new next keys: Includes digests of newly generated next keys
5. Satisfies dual thresholds:
   • Prior next threshold: Signed with the controller's pre-rotated keys
   • New current threshold: Signed with the new current keys

Step 9: Rotation Event Propagation

The controller:

• Signs the rotation event with both the prior next keys and new current keys
• Submits the event to the witness pool
• Witnesses verify the dual threshold satisfaction
• Witnesses create and distribute receipts
• The rotation is anchored in the KERL

Step 10: Authority Transfer Complete

After successful rotation:

• The custodian's keys are revoked and no longer valid
• The custodian cannot create any new valid signatures
• The controller (or new custodian) holds the new current signing authority
• The controller retains rotation authority via the new next keys
• The KEL provides cryptographic proof of the authority transfer

Phase 4: Verification and Validation

Step 11: Validator Processing

Any validator verifying signatures after rotation:

1. Retrieves the complete KEL for the AID
2. Processes events in sequence to determine current key state
3. Identifies that a rotation occurred, invalidating prior keys
4. Validates that the rotation satisfied both thresholds
5. Accepts only signatures from the new current keys
6. Rejects any signatures from the revoked custodian keys

Technical Requirements

Cryptographic Requirements

Key Generation Standards

All keys used in custodial rotation must meet KERI's cryptographic strength requirements:

• Minimum entropy: 128 bits for cryptographic strength
• Supported algorithms: Ed25519, ECDSA (secp256k1, secp256r1), or other KERI-supported signature schemes
• CESR encoding: All keys must be qualified with appropriate derivation codes
• Secure generation: Keys must be generated using CSPRNG (Cryptographically Secure Pseudorandom Number Generator)

Digest Computation

Next key digests must use:

• Blake3-256 or SHA-256 hash functions
• Qualified digest format with CESR derivation codes
• Proper ordering in the next key digest list to support fractional weights if used

Dual Threshold Satisfaction

Rotation events must cryptographically satisfy:

1. Prior next threshold: Signatures from keys that hash to the digests in the prior event's next key digest list
2. Current threshold: Signatures from the new current keys being established

Both thresholds must be independently verifiable by validators processing the KEL.

Timing Considerations

Key Lifecycle Management

• Pre-rotation timing: Next keys should be generated and committed before current keys are exposed to operational risk
• Rotation frequency: Balance security (more frequent rotation) against operational complexity
• Grace periods: Consider implementing notification periods before rotating away from custodians
• Emergency rotation: Maintain capability for immediate rotation in compromise scenarios

Witness Confirmation

Rotation events require:

• Submission to the designated witness pool
• Receipt collection from a threshold of witnesses (per TOAD)
• Propagation time for witnesses to achieve consensus via KAACE
• Network latency considerations for distributed witness pools

Validator Synchronization

After rotation:

• Validators must retrieve updated KEL to learn new key state
• OOBI mechanisms enable discovery of updated state
• Watchers provide ambient verification of rotation events
• Caching systems must invalidate stale key state

Error Handling

Rotation Failure Scenarios

1. Insufficient witness receipts: If rotation event doesn't achieve witness threshold, the rotation is not established. Controller must retry or investigate witness availability.

2. Threshold satisfaction failure: If rotation event signatures don't satisfy both required thresholds, witnesses will reject the event. Controller must regenerate with correct signatures.

3. Digest mismatch: If exposed prior next keys don't hash to the committed digests, the rotation is invalid. This indicates either key generation error or potential attack.

4. Custodian interference: If custodian attempts to create conflicting events after rotation, duplicity detection mechanisms will identify the conflict. Validators will reject custodian's events based on KEL ordering.

Recovery Procedures

• Lost rotation keys: If controller loses pre-rotated keys, the AID cannot be rotated. This is an irrecoverable failure requiring AID abandonment. Emphasizes importance of secure key backup.

• Premature key exposure: If next keys are accidentally exposed before rotation, controller should immediately rotate to new keys to maintain security.

• Witness pool failure: If witness pool becomes unavailable, controller may need to rotate to a new witness pool configuration, which itself requires a rotation event.

Usage Patterns

Typical Scenarios

Scenario 1: Cloud Agent Delegation

A user wants to use a cloud-based KERIA agent for convenience while maintaining ultimate control:

1. User generates AID with custodial rotation structure
2. User delegates signing authority to KERIA agent
3. Agent handles routine signing operations (credential issuance, message signing)
4. User retains rotation authority on personal device or hardware security module
5. If user wants to change agents or suspects compromise, user rotates to new keys

Scenario 2: Enterprise Service Provider

An organization contracts with a managed identity service:

1. Organization establishes AID with custodial rotation
2. Service provider receives signing authority for operational efficiency
3. Provider signs on behalf of organization for business processes
4. Organization maintains rotation authority for governance compliance
5. Contract termination triggers rotation, immediately revoking provider access

Scenario 3: Multi-Custodian Architecture

A high-security application uses multiple custodians with threshold signing:

1. Controller establishes AID with weighted threshold (e.g., "2/3" of custodians)
2. Three custodians each hold partial signing authority
3. Operations require cooperation of any two custodians
4. Controller retains exclusive rotation authority
5. Compromise of single custodian doesn't compromise system
6. Controller can rotate to new custodian set if needed

Best Practices

Key Management

1. Secure rotation key storage: Store pre-rotated keys in HSM, TEE, or secure offline storage
2. Key backup: Maintain encrypted backups of rotation keys with recovery procedures
3. Key generation: Use high-entropy sources and proper CSPRNG for all key generation
4. Key rotation schedule: Establish regular rotation cadence based on risk assessment
5. Emergency procedures: Document and test emergency rotation procedures

Threshold Design

1. Separation of concerns: Ensure current and next thresholds clearly separate signing from rotation authority
2. Fractional weights: Use weighted thresholds for nuanced control in multi-custodian scenarios
3. Threshold testing: Verify threshold configurations before operational deployment
4. Documentation: Clearly document threshold rationale and authority distribution

Operational Security

1. Custodian vetting: Thoroughly evaluate custodial agents before delegation
2. Monitoring: Implement monitoring of custodian signing activity
3. Audit trails: Maintain comprehensive logs of all signing operations
4. Incident response: Prepare procedures for rapid rotation in compromise scenarios
5. Regular review: Periodically review custodial relationships and rotate as needed

Witness Configuration

1. Diverse witness pool: Use geographically and organizationally diverse witnesses
2. Witness availability: Ensure witness pool has sufficient availability for rotation events
3. TOAD setting: Configure threshold of accountable duplicity appropriately for security requirements
4. Witness rotation: Plan for rotating witness pool configuration if needed

Integration Considerations

Application Integration

Applications using custodial rotation must:

1. KEL verification: Always verify current key state from KEL before accepting signatures
2. Rotation awareness: Handle key state changes gracefully when rotations occur
3. Caching strategy: Implement appropriate caching with invalidation on rotation
4. Error handling: Properly handle signatures from revoked keys after rotation

Wallet Integration

Wallets supporting custodial rotation should:

1. Clear authority display: Show users which keys have signing vs. rotation authority
2. Rotation UI: Provide intuitive interface for initiating rotations
3. Key backup: Ensure rotation keys are properly backed up
4. Status indication: Clearly indicate when custodial delegation is active

Agent Integration

Custodial agents must:

1. Authority limits: Respect the limitation to signing authority only
2. Rotation detection: Detect when rotation has revoked their authority
3. Graceful degradation: Stop signing operations after rotation without data loss
4. Audit logging: Maintain comprehensive logs of all signing operations

Protocol Compatibility

Custodial rotation integrates with:

1. ACDC issuance: Custodians can issue credentials on behalf of controllers
2. IPEX exchanges: Custodians can participate in presentation exchanges
3. OOBI discovery: Rotation events propagate through OOBI mechanisms
4. TEL registries: Custodians can manage credential registries with signing authority

Security Properties

Controller Sovereignty

Custodial rotation preserves controller sovereignty through:

• Unilateral rotation capability without custodian cooperation
• Cryptographic proof of authority transfer
• No reliance on custodian honesty for rotation
• Immediate revocation of custodian authority upon rotation

Forward Security

The mechanism provides forward security:

• Compromise of custodian signing keys doesn't compromise rotation authority
• Rotation keys remain protected even if signing keys are exposed
• Future rotations remain secure after custodian compromise

Duplicity Detection

KERI's duplicity detection mechanisms ensure:

• Any attempt by custodian to create conflicting events is detectable
• Validators can identify and reject unauthorized custodian actions
• Ambient verifiability enables ecosystem-wide detection

Non-Repudiation

All operations maintain non-repudiation:

• Custodian signatures are cryptographically attributable
• Rotation events are cryptographically verifiable
• Complete audit trail in KEL
• No party can deny their actions

Implementation Considerations

State Management

Implementations must track:

• Current key state (which keys have signing authority)
• Next key commitments (digests of rotation keys)
• Threshold configurations (current and next)
• Witness pool composition and receipts
• Complete KEL history for verification

Performance Optimization

For efficient custodial rotation:

• Cache current key state with KEL-based invalidation
• Pre-compute threshold satisfaction for common scenarios
• Optimize witness receipt collection
• Use efficient KEL storage and retrieval

Testing Requirements

Thorough testing should cover:

• Successful rotation scenarios
• Failed rotation attempts
• Custodian behavior after rotation
• Threshold satisfaction edge cases
• Witness pool failure scenarios
• Concurrent operation handling

Documentation Requirements

Implementations should document:

• Authority distribution model
• Threshold configuration rationale
• Key management procedures
• Rotation procedures and triggers
• Emergency response procedures
• Integration requirements for applications