A hierarchical delegation pattern in KERI where both delegator and delegate must cryptographically commit to the delegation relationship through mutual seals in their respective key events, enabling recursive application of superseding recovery rules across multiple delegation levels to protect lower-level keys through higher-level security.
Related Concepts
No related concepts available
Comprehensive Explanation
nested-cooperative-delegated-identifiers
Process Definition
Nested cooperative delegated identifiers represent a fundamental delegation mechanism in KERI that enables hierarchical key management through bilateral cryptographic commitments. Unlike traditional unilateral delegation models found in conventional PKI systems, KERI's cooperative delegation requires active participation from both parties:
The delegate creates a corresponding cryptographic commitment in its establishment event via a seal pointing back to the delegating event
Each party signs their respective commitments, creating a bidirectional cryptographic binding
This process accomplishes several critical objectives:
Mutual consent enforcement: Neither party can unilaterally establish or modify the delegation relationship
Verifiable delegation chains: All commitments are cryptographically verifiable through the KEL
Hierarchical security inheritance: Lower-level identifiers benefit from the security posture of their delegating ancestors
Implementation Notes
Critical Implementation Considerations
Seal Construction and Verification
Seal Format: Seals in KERI events are represented as objects in the anchors (a) array with three fields:
i: The identifier being sealed (the delegate's AID for delegation seals)
s: The sequence number of the event being sealed
d: The SAID (digest) of the event being sealed
Implementers must ensure that:
The SAID is computed over the complete serialized event using the specified hash algorithm
The seal is included in the signed portion of the event to prevent tampering
Both delegator and delegate seals reference each other's events by SAID for bidirectional verification
Event Ordering and Escrow
KERI's fully asynchronous nature means events may arrive out of order. Implementations must:
Escrow out-of-order events: If a delegate's inception event arrives before the delegator's authorizing event, escrow it until the dependency is resolved
Maintain escrow state: Track which events are waiting for which dependencies
Process escrowed events: When a dependency arrives, re-process all escrowed events that depend on it
Timeout handling: Implement timeouts for escrowed events to prevent indefinite waiting
Witness Configuration Strategy
Hierarchical witness allocation:
Root delegators should use 5-7 witnesses with TOAD threshold of 4-5 for maximum security
Mid-level delegates can use 3-5 witnesses with TOAD threshold of 2-3 for balanced security/performance
Leaf delegates may use 1-3 witnesses with TOAD threshold of 1-2 for performance
Witness pool separation:
Consider using different witness pools for different delegation levels to prevent correlated failures
Ensure witness availability matches the criticality of the identifier
Document witness requirements in delegation governance policies
Verify authority: Ensure only the immediate parent delegator can issue superseding rotations
Compromise recovery: Higher-level keys can rotate out compromised lower-level keys through superseding rotations
The "nested" aspect refers to the recursive application of this cooperative delegation pattern across multiple hierarchical levels, creating arbitrarily deep delegation trees. The "cooperative" aspect emphasizes the bilateral nature of the commitment process, distinguishing it from traditional top-down delegation models.
Process Flow
Step 1: Delegator Initiates Delegation
The delegation process begins when a delegator AID (Autonomic Identifier) decides to delegate authority to a new delegate identifier:
Delegator creates delegation seal: The delegator constructs a seal containing a cryptographic commitment to the delegate's inception event
Seal anchoring: This seal is embedded in either:
A rotation event if the delegator is simultaneously rotating keys
An interaction event if only anchoring the delegation without key changes
Delegator events should achieve witness consensus before delegate inception
The KAACE algorithm ensures witnesses agree on event ordering
TOAD (Threshold of Accountable Duplicity) determines minimum witness confirmations
Typical confirmation windows range from seconds to minutes depending on network conditions
Recovery Timing:
Superseding rotations should be issued promptly upon compromise detection
The recovery window depends on the depth of the delegation tree
Deeper trees require more time for recovery events to propagate
Watchers provide ambient monitoring to detect compromise quickly
Error Handling
Missing Delegation Seals:
If a delegate's inception event lacks a seal to the delegator, validation fails
If a delegator's event lacks a seal to the delegate, the delegation is incomplete
Validators must reject events with malformed or missing seals
Error: "Delegation seal missing or invalid"
Seal Mismatch:
If the delegator's seal commits to a different event than the delegate references, validation fails
The SAID in the delegator's seal must match the SAID of the delegate's inception event
The delegate's seal must reference the correct delegator event by SAID
Error: "Delegation seal mismatch - bidirectional commitment failed"
Broken Delegation Chains:
If any link in a nested delegation chain is invalid, the entire chain fails validation
Validators must verify each level recursively up to the root
Missing or corrupted KEL entries break the chain
Error: "Delegation chain broken at level N"
Unauthorized Superseding:
Only the immediate parent delegator can issue superseding rotations
Attempts by non-parent identifiers to supersede must be rejected
Superseding events must properly reference the delegation relationship
Error: "Unauthorized superseding rotation - not immediate parent"
Witness Threshold Failures:
If insufficient witnesses confirm delegation events, the delegation is not stable
The TOAD threshold must be met for both delegator and delegate events
Validators should wait for threshold confirmation before accepting delegations
Error: "Insufficient witness confirmations for delegation"
Usage Patterns
Enterprise Hierarchical Key Management
Scenario: A large corporation needs to manage identifiers for divisions, departments, and individual employees while maintaining centralized security control.
Implementation:
Root AID: Corporate root identifier with highest security (HSM-protected keys)
Division AIDs: Each division receives a delegated identifier from the root
Department AIDs: Departments receive delegated identifiers from their division
Employee AIDs: Individual employees receive delegated identifiers from their department
Benefits:
Centralized recovery: If an employee's keys are compromised, the department can issue a superseding rotation
Cascading security: Root-level security protects all descendant identifiers
Flexible revocation: Delegation can be revoked by rotating the parent without the delegate's cooperation
This creates a verifiable chain of trust from GLEIF to end entities
With DID Methods:
Delegated KERI identifiers can be expressed as did:keri or did:webs
The delegation relationship is encoded in the DID document metadata
DID resolution must verify the complete delegation chain
Interoperability with other DID methods requires delegation chain translation
Conclusion
Nested cooperative delegated identifiers represent a powerful mechanism for building scalable, secure, and recoverable hierarchical identity systems. By requiring bilateral cryptographic commitments and enabling recursive superseding recovery, KERI's delegation model provides unique security properties not found in traditional PKI systems. The cooperative nature ensures mutual consent while the nested structure enables organizational hierarchies to be directly represented in the cryptographic infrastructure. This makes nested cooperative delegation particularly well-suited for enterprise identity management, multi-tenant services, IoT deployments, and any scenario requiring verifiable delegation chains with built-in compromise recovery capabilities.
Create new inception: Generate a fresh inception event for the delegate with new, uncompromised keys
Issue superseding rotation: The delegator issues a rotation event with a seal to the new inception
Propagate recovery: Notify all validators and watchers of the superseding event
Update state: Validators must recognize the superseding event and discard the compromised KEL branch
Performance Optimization
Caching delegation chains:
Cache verified delegation chains to avoid repeated verification
Invalidate cache when any event in the chain is superseded
Use SAID-based cache keys for efficient lookup
Parallel verification:
Verify different branches of delegation trees in parallel
Use worker pools for KEL verification at each level
Aggregate results to determine overall chain validity
Lazy loading:
Don't load entire KELs for deep delegation chains
Load only the events necessary for delegation verification
Use SAID references to minimize data transfer
Security Hardening
Delegation depth limits:
Enforce maximum delegation depth (recommend 5 levels) to prevent abuse
Reject delegation chains exceeding the configured limit
Document depth limits in system governance
Seal validation:
Always verify both directions of the bilateral seal commitment
Reject delegations with missing or mismatched seals
Validate that seal SAIDs match the actual event digests
Witness threshold enforcement:
Require TOAD threshold to be met before accepting delegation events as stable
Implement timeout mechanisms for witness confirmation
Alert on threshold failures that may indicate attacks
Integration with KERIA Agents
When implementing nested delegation in KERIA cloud agents:
Multi-tenant isolation: Ensure delegation relationships don't leak between tenants
Delegation APIs: Provide REST endpoints for creating and verifying delegations
Notification system: Alert controllers when delegation events occur
Backup and recovery: Ensure delegation relationships are preserved in backups
Audit logging: Log all delegation operations for compliance and debugging
Testing Strategies
Unit tests:
Test seal construction and verification
Test bilateral commitment validation
Test superseding rotation logic
Test escrow and out-of-order event handling
Integration tests:
Test multi-level delegation chains (3-5 levels)
Test recovery scenarios at each level
Test witness confirmation across delegation levels
Test performance with large delegation trees
Security tests:
Test unauthorized superseding attempts
Test seal tampering detection
Test delegation depth limit enforcement
Test witness threshold bypass attempts
Common Pitfalls
Forgetting reciprocal seals: Both delegator and delegate must include seals; missing either breaks the delegation
Incorrect SAID computation: Seals must reference the exact SAID of the target event; mismatches cause validation failures
Insufficient witness thresholds: Low TOAD values compromise security; use appropriate thresholds for each level
Ignoring event ordering: Out-of-order events must be escrowed; processing them immediately causes validation errors
Not implementing superseding: Recovery is a critical feature; implementations without superseding support are incomplete
Excessive delegation depth: Very deep trees (>5 levels) become difficult to manage and verify; limit depth appropriately