Comprehensive Explanation

partial-rotation

Process Definition

Partial rotation is a sophisticated key management mechanism within KERI that extends the fundamental pre-rotation concept to enable more flexible and secure key rotation strategies. Unlike standard rotation where all pre-rotated keys must be exposed and rotated simultaneously, partial rotation allows controllers to selectively expose and rotate only a subset of their pre-committed keypairs while maintaining others in reserve (unexposed).

The process accomplishes several critical objectives:

1. Selective Key Exposure: Controllers can reveal only the keys necessary for current operations, minimizing attack surface
2. Reserve Key Management: Unexposed keys remain cryptographically committed but hidden for future use
3. Flexible Authority Delegation: Enables separation of signing authority from rotation authority
4. Enhanced Security Posture: Provides defense-in-depth through layered key management strategies

Partial rotation is used when controllers need to:

• Delegate operational signing to custodial agents while retaining ultimate control
• Maintain backup rotation keys in secure reserve
• Implement hierarchical key management with different security levels
• Support gradual key exposure strategies

Key participants in partial rotation include:

• Controller: The entity managing the AID and making rotation decisions
• Custodial Agent (optional): Entity granted signing authority through partial rotation
• Witnesses: Entities that verify and receipt the rotation event
• Validators: Entities that verify the rotation satisfies both current and prior thresholds

Process Flow

Partial rotation follows a precise sequence of operations defined in Document 1:

Step 1: Syntax Preparation

The rotation event must include two critical structural elements:

Next Threshold Field (nt): All establishment events gain a new field specifying the minimum number of signatures required from the next pre-rotated key set. This field is a string representation of an integer or fractional weight threshold:

"nt": "3"

This represents a requirement for 3 signatures from the next key set, independent of how many keys are in that set.

Next Keys Field (n) Structure: The n field changes from a single XORed digest string to an ordered list of individual key digests. Each digest corresponds to one next public key in sequential order:

"n": [
  "ETNZH3ULvYawyZ-i0d8JZU6JR2nmAoAfSVPzhzS6b5CM",
  "EYAfSVPzhzaU6JR2nmoTNZH3ULvwyZb6b5CMi0d8JZAS",
  "EnmwyZdi0d8JZAoTNZYAfSVPzhzaU6JR2H3ULvS6b5CM",
  "ETNZH3ULvS6bYAfSVPzhzaU6JR2nmwyZfi0d8JZ5s8bk",
  "EJR2nmwyZ2i0dzaU6ULvS6b5CM8JZAoTNZH3YAfSVPzh"
]

This ordered list structure serves multiple purposes:

• Enables partial rotation verification
• Preserves position information for fractionally-weighted thresholds
• Allows validators to verify each multi-sig member's key digest appears in expected position

Step 2: Key Selection and Unblinding

The controller selects which subset of pre-rotated keys to expose in the current rotation. This involves:

1. Reference Prior Event: Identify the most recent prior establishment event containing the next key digest list
2. Select Keys: Choose which keys from that digest list to expose (unblind)
3. Verify Threshold: Ensure selected keys satisfy the prior next threshold (nt from prior event)
4. Prepare Current Keys: The selected keys become the current signing keys in the rotation event's k field

The prior next key list consists of the public keys that were previously committed to via their digests. Only the subset being rotated needs to be revealed.

Step 3: Dual Threshold Validation

A valid partial rotation requires satisfying two distinct thresholds as specified in Document 12:

Current Threshold Validation:

• The rotation event's kt field specifies the current signing threshold
• Attached signatures must satisfy this threshold
• Signatures are verified against the public keys in the rotation event's k field
• This establishes the new key state

Prior Next Threshold Validation:

• The prior establishment event's nt field specifies the prior next threshold
• The rotation must be signed by keys from the prior next key digest list
• The number of signing keys must satisfy the prior next threshold
• This proves authorization from the previously committed key set

This dual-threshold mechanism 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 4: Reserve Key Management

Keys not exposed in the current rotation remain in reserve:

1. Cryptographic Commitment Maintained: The digests of unexposed keys remain in the KEL
2. Future Availability: Reserved keys can be exposed in subsequent rotations
3. Security Enhancement: Unexposed keys cannot be compromised if they remain unknown
4. Flexible Strategy: Controllers can expose reserved keys as needed

Step 5: Event Anchoring

The rotation event is anchored in the KEL:

1. Backward Chaining: The event includes a digest of the prior event
2. Forward Chaining: The event commits to new next keys (potentially partial)
3. Witness Receipting: Witnesses verify and receipt the event
4. State Update: The key state advances to reflect the new current keys and thresholds

Technical Requirements

Cryptographic Requirements

Partial rotation imposes specific cryptographic constraints:

Digest Consistency: All key digests must use consistent cryptographic algorithms. The derivation code prepended to each digest specifies the algorithm used. Validators must verify digest derivation codes match expected algorithms.

Signature Verification: Each signature must be verified against its corresponding public key using the algorithm specified by the key's derivation code. The signature attachment must include an index indicating which key from the current or prior key list was used.

Threshold Satisfaction: Both current and prior thresholds must be satisfied. For fractionally-weighted thresholds, the sum of weights from signing keys must meet or exceed the threshold value.

Ordered List Integrity: The next key digest list order must be preserved. Position in the list determines which key corresponds to which signer in multi-sig scenarios.

Timing Considerations

Partial rotation has specific timing requirements:

Sequential Processing: Rotation events must be processed in strict sequence number order. Out-of-order events must be escrowed until prior events are received and validated.

Witness Coordination: For indirect mode operations, witnesses must coordinate to achieve agreement on the rotation event before it becomes stable. The KAACE algorithm governs this coordination.

Key Exposure Timing: Reserved keys should only be exposed when needed. Premature exposure increases attack surface without providing operational benefit.

Recovery Window: Controllers should maintain sufficient reserved keys to enable recovery from key compromise scenarios without requiring complete identifier abandonment.

Error Handling

Partial rotation implementations must handle several error conditions:

Threshold Violation: If either current or prior threshold is not satisfied, the rotation event is invalid and must be rejected. This prevents unauthorized rotations.

Digest Mismatch: If an exposed public key does not match its committed digest from the prior event, the rotation is invalid. This prevents key substitution attacks.

Sequence Number Errors: If the rotation event's sequence number does not follow the prior event, it must be escrowed or rejected depending on whether it's out-of-order or duplicitous.

Signature Verification Failures: Any signature that fails cryptographic verification invalidates the rotation. All signatures must verify successfully.

Duplicity Detection: If multiple conflicting rotation events exist for the same sequence number, duplicity is detected and the controller is marked as duplicitous.

Usage Patterns

Reserve Rotation Pattern

Reserve rotation is a primary use case where controllers maintain backup keypairs that remain unexposed. As documented in Document 8:

Strategic Key Management:

• Pre-rotated key pairs are designated in an establishment event
• Keys are held in reserve rather than immediately exposed
• Keys remain unexposed at the next establishment event
• Provides enhanced security through selective key exposure

Security Benefits:

• Defense in Depth: Multiple layers of pre-rotated keys provide fallback options
• Reduced Attack Surface: Unexposed keys cannot be targeted
• Flexible Recovery: Reserved keys enable recovery from compromise
• Long-term Planning: Controllers can plan multiple future rotations

Implementation Strategy:

1. Generate multiple pre-rotated key pairs
2. Commit to all keys via digests in next key list
3. Expose only minimum necessary keys in each rotation
4. Maintain reserved keys in secure storage
5. Expose reserved keys only when needed

Custodial Rotation Pattern

Custodial rotation enables sophisticated delegation as described in Document 5:

Authority Separation:

• Signing Authority: Delegated to custodial agent for operational signing
• Rotation Authority: Retained by original controller for key management
• Implemented through threshold and key list structuring
• Enables "fire the custodian" capability without custodian cooperation

Business Model Enablement: As noted in Document 10, custodial rotation addresses a critical adoption challenge:

• Mainstream Users: 99% of people may not feel comfortable managing their own keys
• Service Model: Enables professionally hosted infrastructure without centralizing control
• Business Model: Software-as-a-service without centralizing control on provider
• Retained Control: Users maintain sovereignty through rotation authority

Implementation Pattern:

1. Controller generates two key sets: signing and rotation
2. Signing keys delegated to custodial agent
3. Rotation keys retained by controller in secure storage
4. Custodial agent performs day-to-day signing operations
5. Controller can rotate keys to revoke custodial agent access

Multi-Signature Group Management

Partial rotation supports sophisticated multi-signature scenarios:

Flexible Membership:

• New members can join existing groups through partial rotation
• Departing members can be removed without exposing all keys
• Threshold adjustments can occur during rotation
• Different members can have different key weights

Threshold Structures:

• Simple majority: "kt": "2" for 3-member group
• Supermajority: "kt": "3" for 4-member group
• Fractional weights: "kt": "0.66" for 66% threshold
• Complex structures: Different thresholds for signing vs. rotation

Best Practices

Key Generation:

• Use cryptographically strong random number generators
• Generate keys in secure environments (HSMs, TEEs)
• Maintain key generation audit trails
• Use consistent derivation codes across key sets

Key Storage:

• Store reserved keys in offline/cold storage
• Use hardware security modules for high-value identifiers
• Implement key splitting for distributed storage
• Maintain encrypted backups with recovery procedures

Rotation Planning:

• Plan multiple rotations in advance
• Maintain sufficient reserved keys for contingencies
• Document rotation procedures and thresholds
• Test rotation procedures before production use

Security Monitoring:

• Monitor for duplicitous rotation attempts
• Track key exposure over time
• Audit rotation events for anomalies
• Implement alerting for unexpected rotations

Integration Considerations

Witness Coordination:

• Ensure witnesses support partial rotation syntax
• Configure witness thresholds appropriately
• Monitor witness agreement on rotation events
• Plan for witness rotation alongside key rotation

Client Implementation:

• Implement dual threshold validation logic
• Support ordered next key digest lists
• Handle reserve key management in key stores
• Provide UI for custodial delegation scenarios

Protocol Compatibility:

• Ensure compatibility with KERI protocol version
• Support both old and new rotation syntax during transition
• Implement backward compatibility where needed
• Test interoperability with other KERI implementations

Governance Integration:

• Document rotation policies in governance frameworks
• Specify threshold requirements for different operations
• Define custodial delegation procedures
• Establish key compromise response procedures