The list structure is critical because:

• Order matters for fractionally-weighted threshold schemes
• Each position corresponds to a specific key in the rotation key set
• Validators can verify that each multi-sig member's key digest appears in the expected position

Key Components

Each element in the ndigs list consists of:

1. Derivation Code: A CESR prefix indicating the digest algorithm (e.g., Blake3-256, SHA3-256)
2. Digest Value: The cryptographic hash of the public rotation key
3. Encoding: Base64 URL-safe encoding for text domain representation

The "qualified" nature means each digest is self-describing through its derivation code, enabling cryptographic agility where different algorithms can coexist in the same system.

Data Format

Field Definitions

In KERI establishment events (inception and rotation), ndigs appears in the n field:

Inception Event Example:

{
  "v": "KERI10JSON0000e6_",
  "t": "icp",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "s": "0",
  "kt": "1",
  "k": ["DSuhyBcPZEZLK-fcw5tzHn2N46wRCG_ZOoeKtWTOunRA"],
  "n": ["EPYuj8mq_PYYsoBKkzX1kxSPGYBWaIya3slgCOyOtlqU"],
  "bt": "2",
  "b": ["BJq7UABlttINuWJh1Xl2lkqZG4NTdUdqnbFJDa6ZyxCC"],
  "c": [],
  "a": []
}

In this example, the n field contains a single-element list with one digest. For multi-signature configurations, the list would contain multiple digests.

Multi-Signature Example:

{
  "n": [
    "ETNZH3ULvYawyZ-i0d8JZU6JR2nmAoAfSVPzhzS6b5CM",
    "EYAfSVPzhzaU6JR2nmoTNZH3ULvwyZb6b5CMi0d8JZAS",
    "EnmwyZdi0d8JZAoTNZYAfSVPzhzaU6JR2H3ULvS6b5CM"
  ]
}

Encoding Format

Each digest in ndigs follows CESR encoding conventions:

1. Derivation Code: First character(s) indicate the algorithm

   • E: Blake3-256 digest
   • F: Blake2b-256 digest
   • G: Blake2s-256 digest
   • H: SHA3-256 digest
   • I: SHA2-256 digest

2. Base64 Encoding: The digest bytes are encoded in Base64 URL-safe format

3. Length: Fixed length determined by the digest algorithm (e.g., 44 characters for 256-bit digests in Base64)

The CESR encoding ensures:

• Self-describing format: The derivation code makes the digest type explicit
• Composability: Multiple primitives can be concatenated and parsed unambiguously
• Dual-domain support: Can be represented in both text and binary domains

Size and Constraints

Minimum Cryptographic Strength: KERI mandates approximately 128 bits of cryptographic strength for all digests, ensuring adequate security against collision attacks.

List Size: The number of elements in ndigs must match:

• The next threshold (nt) specified in the establishment event
• The number of rotation keys the controller wishes to pre-commit to
• For partial rotation scenarios, may exceed the threshold to keep keys in reserve

Validation Constraints:

• Each digest must be a valid CESR-encoded primitive
• The list cannot be empty for transferable identifiers
• For non-transferable identifiers, ndigs is typically empty or omitted

Operations

Creation and Initialization

During Inception:

1. Key Generation: Controller generates rotation key pairs

   # Pseudocode for key generation
   rotation_keypairs = generate_keypairs(count=threshold)
   

2. Digest Computation: Compute cryptographic digests of public keys

   ndigs = []
   for keypair in rotation_keypairs:
       public_key = keypair.public_key
       digest = blake3_hash(public_key)
       qualified_digest = cesr_encode(digest, derivation_code='E')
       ndigs.append(qualified_digest)
   

3. Inclusion in Event: Add ndigs list to the n field of the inception event

4. Secure Storage: Store the rotation private keys securely, separate from current signing keys

During Rotation:

1. Reveal Previous Keys: The keys committed to in the previous event's ndigs are now revealed in the k field

2. Commit to New Keys: Generate new rotation keys and compute their digests for the new ndigs

3. Verification: Validators verify that revealed keys hash to the previously committed digests

Updates and Modifications

ndigs is immutable once included in a signed establishment event. Updates occur through the rotation mechanism:

1. Pre-Rotation Cycle:

   • Event N contains n field with digests of keys for rotation N+1
   • Event N+1 reveals those keys in k field and commits to new keys in its n field
   • Event N+2 reveals the keys from N+1's n field, and so on

2. Partial Rotation:

   • Not all pre-committed keys need to be revealed in the next rotation
   • Some keys can remain in reserve (unexposed)
   • The next rotation can reveal previously reserved keys

3. Threshold Changes:

   • The nt (next threshold) field specifies how many signatures from the pre-rotated keys are required
   • This can differ from the current threshold kt

Verification and Validation

Validator Responsibilities:

1. Digest Verification: When a rotation event occurs, validators must:

   # Pseudocode for verification
   def verify_rotation(current_event, prior_event):
       revealed_keys = current_event['k']
       committed_digests = prior_event['n']
       
       for key, digest in zip(revealed_keys, committed_digests):
           computed_digest = blake3_hash(key)
           if cesr_encode(computed_digest) != digest:
               raise ValidationError("Key does not match committed digest")
   

2. Threshold Validation: Verify that the number of signatures satisfies both:

   • The current threshold from the rotation event
   • The prior next threshold from the previous establishment event

3. Structural Validation:

   • Ensure ndigs is a properly formatted list
   • Verify each element is a valid CESR-encoded digest
   • Check that the list length is appropriate for the threshold

Security Properties Verified:

• Forward Security: Compromise of current keys doesn't compromise pre-rotated keys (they're hidden by digests)
• Rotation Authority: Only the entity possessing the pre-committed keys can perform valid rotations
• Duplicity Detection: Any attempt to rotate to different keys than committed creates detectable inconsistency

Usage Context

In KERI Protocol

ndigs is fundamental to KERI's establishment event structure:

Inception Events (icp):

• Establish the initial ndigs commitment
• Define the first set of rotation keys
• Set the foundation for the pre-rotation chain

Rotation Events (rot):

• Reveal keys committed to in the previous event's ndigs
• Establish new ndigs for the next rotation
• Maintain the unbroken chain of cryptographic commitments

Interaction Events (ixn):

• Do not contain ndigs (non-establishment events)
• Do not change key state

Lifecycle Management

Phase 1: Generation

• Controller generates rotation key pairs
• Computes digests for ndigs
• Stores private keys securely offline

Phase 2: Commitment

• ndigs included in establishment event
• Event signed and published to witnesses
• Cryptographic commitment becomes part of KEL

Phase 3: Revelation

• During rotation, pre-committed keys are revealed
• Validators verify keys match committed digests
• New ndigs established for future rotation

Phase 4: Retirement

• Once revealed and rotated, keys are no longer used for rotation
• May be retained for historical verification
• New rotation keys take their place

Related Structures

Current Keys (k field):

• The currently active signing keys
• Revealed from the previous event's ndigs
• Used for signing non-establishment events and the current rotation

Next Threshold (nt field):

• Specifies how many signatures from ndigs keys are required
• Can differ from current threshold kt
• Enables flexible threshold management

Key Event Log (KEL):

• ndigs entries form a verifiable chain through the KEL
• Each event's ndigs commits to the next event's keys
• Provides complete audit trail of key management

Witnesses:

• Observe and receipt events containing ndigs
• Provide duplicity detection if controller attempts inconsistent rotations
• Enable distributed consensus on key state

Security Implications

Post-Quantum Security

The digest-based commitment in ndigs provides post-quantum security properties:

1. Quantum Resistance: Even if quantum computers can break the signature algorithm, they cannot efficiently find pre-images of the hash digests

2. Forward Hiding: The pre-rotated keys remain hidden until revelation, protecting against future quantum attacks on the key derivation

3. Recovery Capability: If current signing keys are compromised, the controller can still rotate using the unexposed pre-rotated keys

Attack Mitigation

Dead Attacks (attacks on stale key state):

• ndigs enables recovery even if old keys are compromised
• The pre-rotation chain ensures continuity of control

Live Attacks (attacks on current keys):

• Pre-rotated keys remain hidden, limiting attacker capabilities
• Attacker cannot rotate to their own keys without the pre-committed keys

Duplicity Attacks:

• Any attempt to rotate to keys not matching ndigs creates detectable duplicity
• Witnesses and watchers can identify inconsistent rotations

Implementation Considerations

Key Management

Implementers must carefully manage the lifecycle of rotation keys:

1. Secure Generation: Use cryptographically secure random number generators
2. Offline Storage: Keep rotation keys offline until needed
3. Separation: Store rotation keys separately from signing keys
4. Backup: Maintain secure backups of rotation keys
5. Destruction: Securely destroy keys after rotation

Performance Optimization

Digest Computation:

• Pre-compute digests during key generation
• Cache digests to avoid recomputation
• Use efficient hash implementations (Blake3 is highly optimized)

Validation:

• Batch verify multiple digests when possible
• Parallelize digest verification for multi-sig scenarios
• Cache validation results for frequently accessed events

Error Handling

Invalid Digests:

• Reject events with malformed ndigs
• Provide clear error messages for debugging
• Log validation failures for security monitoring

Threshold Mismatches:

• Verify ndigs list length matches threshold requirements
• Handle partial rotation scenarios correctly
• Validate both current and prior thresholds

Advanced Scenarios

Partial Rotation

ndigs supports partial rotation where not all pre-committed keys are revealed:

{
  "n": [
    "ETNZH3ULvYawyZ-i0d8JZU6JR2nmAoAfSVPzhzS6b5CM",
    "EYAfSVPzhzaU6JR2nmoTNZH3ULvwyZb6b5CMi0d8JZAS",
    "EnmwyZdi0d8JZAoTNZYAfSVPzhzaU6JR2H3ULvS6b5CM",
    "ETNZH3ULvS6bYAfSVPzhzaU6JR2nmwyZfi0d8JZ5s8bk",
    "EJR2nmwyZ2i0dzaU6ULvS6b5CM8JZAoTNZH3YAfSVPzh"
  ],
  "nt": "3"
}

In the next rotation, only 3 of the 5 pre-committed keys might be revealed, keeping 2 in reserve for future rotations.

Custodial Rotation

ndigs enables custodial key management patterns:

1. Signing Authority: Custodian holds current signing keys
2. Rotation Authority: Original controller retains rotation keys
3. Revocation: Controller can "fire" custodian by rotating to new keys

This is implemented through careful threshold configuration and key distribution.

Delegated Identifiers

For delegated AIDs, ndigs works in conjunction with delegation:

1. Delegator Approval: Delegator must approve rotation events
2. Cooperative Rotation: Both delegator and delegate participate
3. Hierarchical Security: Delegation tree maintains security through ndigs at each level

Conclusion

ndigs represents a fundamental innovation in KERI's approach to key management. By using cryptographic digests to commit to future rotation keys without exposing them, KERI achieves:

• Post-quantum security through digest-based commitments
• Recovery from key compromise via unexposed rotation keys
• Flexible key management supporting partial rotation and custodial scenarios
• Verifiable key state through the KEL audit trail

The ndigs mechanism is essential to KERI's security model and distinguishes it from traditional PKI systems that lack secure key rotation capabilities. Understanding ndigs is crucial for implementing KERI-based identity systems and for appreciating the protocol's innovative approach to decentralized key management.

Performance Optimization

1. Caching: Cache computed digests to avoid recomputation:

   • Cache during key generation
   • Cache validation results for frequently accessed events
   • Invalidate cache appropriately during rotations

2. Parallel Processing: For multi-signature scenarios, parallelize:

   • Digest computation during key generation
   • Digest verification during validation
   • Signature verification across multiple keys

3. Batch Operations: When processing multiple events, batch digest operations to leverage CPU cache locality and SIMD instructions.

Error Handling

1. Malformed ndigs: Reject events with:

   • Invalid CESR encoding
   • Incorrect digest lengths
   • Unsupported derivation codes
   • Empty lists for transferable identifiers

2. Threshold Mismatches: Handle cases where:

   • ndigs list length doesn't match threshold requirements
   • Revealed keys don't satisfy prior next threshold
   • Current signatures don't satisfy current threshold

3. Logging and Monitoring: Implement comprehensive logging:

   • Log all validation failures with context
   • Monitor for potential security issues (repeated validation failures)
   • Track rotation events for audit purposes

Security Considerations

1. Key Separation: Maintain strict separation between:

   • Current signing keys (hot storage, frequently accessed)
   • Rotation keys (cold storage, rarely accessed)
   • Backup keys (offline storage, emergency access only)

2. Partial Rotation Support: Implement partial rotation correctly:

   • Track which keys have been revealed vs. reserved
   • Validate that revealed keys match committed digests
   • Handle threshold satisfaction with subset of keys

3. Duplicity Detection: Integrate with duplicity detection mechanisms:

   • Compare ndigs across different versions of the same event
   • Alert on inconsistent rotation attempts
   • Maintain evidence of duplicitous behavior

Testing Requirements

1. Unit Tests: Test individual components:

   • Digest computation with various algorithms
   • CESR encoding/decoding
   • Threshold validation logic
   • Partial rotation scenarios

2. Integration Tests: Test complete workflows:

   • Inception with ndigs
   • Rotation revealing committed keys
   • Multi-signature coordination
   • Error handling paths

3. Security Tests: Verify security properties:

   • Attempt rotation with wrong keys (should fail)
   • Verify post-quantum security properties
   • Test duplicity detection
   • Validate threshold enforcement

Interoperability

1. Cross-Implementation Compatibility: Ensure ndigs format is compatible across:

   • KERIpy (Python reference implementation)
   • KERIox (Rust implementation)
   • SignifyTS (TypeScript implementation)
   • Other KERI implementations

2. Version Compatibility: Handle version differences:

   • Support multiple CESR versions
   • Gracefully handle unknown derivation codes
   • Maintain backward compatibility where possible

3. Witness Coordination: Ensure ndigs handling works correctly with:

   • Multiple witness configurations
   • Witness rotation scenarios
   • Distributed consensus mechanisms