Comprehensive Explanation

key-management

Process Definition

Key management in KERI represents a comprehensive framework for handling cryptographic keys throughout their entire lifecycle, from initial generation through eventual destruction or abandonment. Unlike traditional PKI systems that rely on centralized certificate authorities, KERI's key management is autonomic - meaning it is self-managing, self-certifying, and does not require external administrative trust.

What It Accomplishes

KERI's key management system accomplishes several critical objectives:

1. Establishes Cryptographic Root-of-Trust: Through self-certifying identifiers derived directly from public keys, eliminating dependency on external authorities
2. Enables Secure Key Rotation: Via the innovative pre-rotation mechanism that provides post-quantum security guarantees
3. Maintains Verifiable Control Authority: Through the Key Event Log (KEL) that provides an auditable history of all key state changes
4. Supports Hierarchical Delegation: Enabling scalable organizational key management through cooperative delegation
5. Provides Compromise Recovery: Through pre-rotated keys that remain unexposed until needed

When It's Used

Key management operations occur at several critical junctures:

• Identifier Inception: When creating a new AID, requiring generation of initial key pairs and pre-rotated keys
• Key Rotation Events: When changing authoritative keys due to security hygiene, compromise, or cryptographic agility needs
• Delegation Operations: When establishing hierarchical control relationships between identifiers
• Witness Configuration: When designating witnesses that require their own key management
• Credential Issuance: When signing ACDCs or other verifiable data structures
• Recovery Scenarios: When responding to key compromise or loss

Key Participants

The key management process involves multiple roles:

• Controllers: Entities that generate, store, and use private keys to control AIDs
• Witnesses: Designated entities that verify and receipt key events, requiring their own key management
• Watchers: Entities that monitor KELs for duplicity detection
• Custodial Agents: Optional third parties granted signing authority while controllers retain rotation authority
• Delegates: Entities receiving delegated authority through cooperative delegation mechanisms

Process Flow

Key Pair Generation and Storage

The key management lifecycle begins with cryptographically secure key generation:

Step 1: Entropy Generation

• Generate high-entropy random seed (minimum 128 bits of cryptographic strength)
• Use CSPRNG (Cryptographically Secure Pseudo-Random Number Generator) or true random number generator
• For hierarchical deterministic keys, this seed serves as the root from which all keys derive

Step 2: Key Pair Derivation

• Apply cryptographic derivation function (e.g., Ed25519 for signing keys)
• Generate both current signing keys and pre-rotated next keys
• For multi-signature AIDs, generate multiple key pairs with defined thresholds

Step 3: Secure Storage

• Store private keys in encrypted keystore (KERI uses LMDB-based storage in KERIpy)
• Implement access controls independent of the keys themselves to prevent poisoning attacks
• For high-security scenarios, use Hardware Security Modules (HSMs) or Trusted Execution Environments (TEEs)
• Separate storage of current signing keys from pre-rotated keys for defense in depth

Key Event Generation and Signing

Step 4: Inception Event Creation

• Construct inception event containing:
  • Current public key(s) in the k field
  • Cryptographic digest of next (pre-rotated) key(s) in the n field
  • Signing threshold (kt) and next threshold (nt)
  • Witness configuration (b for witness AIDs, bt for witness threshold)
• Sign the inception event with current private key(s)
• For self-addressing AIDs, the AID prefix is derived from the digest of this inception event

Step 5: Key Event Log Maintenance

• Append signed events to the KEL
• Each event includes digest of previous event (p field) creating hash chain
• Witnesses receipt events, providing distributed validation
• KEL serves as authoritative record of key state history

Key Rotation Process

Step 6: Pre-Rotation Commitment

• During inception or previous rotation, commit to next keys via cryptographic digest
• Next keys remain unexposed and secured separately from current operational keys
• This commitment is cryptographically binding and cannot be changed without detection

Step 7: Rotation Event Execution

• When rotation is needed, construct rotation event containing:
  • Previous event digest (p)
  • Current keys being rotated to (previously pre-rotated keys) in k field
  • New pre-rotated key digests in n field
  • Updated thresholds if changing
• Sign rotation event with the pre-rotated keys (now becoming current)
• Validators verify that revealed keys match previously committed digests

Step 8: Partial Rotation (Optional)

• For advanced scenarios, rotate only subset of pre-rotated keys
• Keep some keys in reserve for future rotations
• Enables custodial rotation where signing authority is delegated but rotation authority retained

State Changes

Key management operations cause specific state transitions:

From Inception to Operational:

• Initial state: No AID exists
• After inception: AID established with initial key state
• KEL contains single inception event
• Witnesses have receipted the inception

From Operational to Rotated:

• Previous state: Current keys active, next keys committed
• After rotation: Previous current keys revoked, pre-rotated keys now current, new next keys committed
• KEL extended with rotation event
• Key state updated for all validators

From Active to Abandoned:

• Rotation to empty next key digest list (ndigers = 0)
• Next threshold must be 0
• No further events accepted after abandonment
• Identifier becomes permanently non-transferable

Decision Points

Key management involves several critical decision points:

Transferable vs Non-Transferable:

• Transferable AIDs support key rotation (require pre-rotation)
• Non-transferable AIDs use fixed keys (simpler but cannot recover from compromise)
• Decision made at inception, cannot be changed

Single-Sig vs Multi-Sig:

• Single signature: One key pair controls the AID
• Multi-signature: Multiple key pairs with threshold requirements
• Affects security, operational complexity, and recovery options

Witness Configuration:

• Number of witnesses (affects availability and security)
• Witness threshold (TOAD - Threshold of Accountable Duplicity)
• Witness rotation policies

Delegation Structure:

• Root AID vs delegated AID
• Delegation depth and hierarchy
• Security vs performance trade-offs at each level

Technical Requirements

Cryptographic Requirements

Minimum Cryptographic Strength:

• All key pairs must provide approximately 128 bits of cryptographic strength
• Compliant algorithms include Ed25519 and ECDSA secp256k1
• Hash functions must provide equivalent strength (SHA-256, Blake3-256)

Key Generation Standards:

• Use CSPRNG or true random number generators
• Sufficient entropy for seed generation (minimum 128 bits)
• Proper key derivation functions for hierarchical deterministic keys

Signature Schemes:

• Non-repudiable digital signatures required for all key events
• Support for multiple signature schemes via CESR derivation codes
• Post-quantum readiness through algorithm agility

Timing Considerations

Key Generation Frequency:

• Occurs relatively infrequently compared to signing operations
• Can use more secure but slower generation methods
• Pre-rotation enables advance generation of next keys

Event Signing Performance:

• Must support high-throughput signing for operational use
• May require separation of signing infrastructure from key generation
• Custodial agents can handle signing while controller retains rotation authority

Rotation Timing:

• Security hygiene: Regular rotation limits exposure window
• Compromise response: Immediate rotation using pre-rotated keys
• Cryptographic agility: Rotation to new algorithms as needed

Witness Receipt Timing:

• Asynchronous receipt collection
• Threshold-based acceptance (don't need all witnesses immediately)
• Escrow mechanisms for out-of-order events

Error Handling

Key Compromise Detection:

• Duplicity detection through witness and watcher networks
• First-seen policy prevents dead attacks
• Ambient duplicity detection enables global consistency verification

Recovery Procedures:

• Use pre-rotated keys to recover from signing key compromise
• Rotation authority separate from signing authority enables recovery
• Witnesses provide independent validation of recovery rotations

Failed Operations:

• Insufficient witness receipts: Retry or adjust witness configuration
• Invalid signatures: Reject events, maintain KEL integrity
• Threshold violations: Event not accepted until threshold met

Delegation Failures:

• Cooperative delegation requires both delegator and delegate participation
• Failed delegation: Neither party can unilaterally complete
• Recovery through delegator's rotation authority

Usage Patterns

Common Scenarios

Individual Identity Management:

• Single-signature transferable AID for personal identity
• Mobile wallet stores keys with biometric protection
• Regular key rotation for security hygiene
• Witness pool for availability when device offline

Organizational Identity:

• Multi-signature AID with threshold (e.g., 2-of-3 executives)
• Hierarchical delegation for departments and roles
• Custodial agents for operational signing
• High-security key storage (HSM) for root keys

IoT Device Management:

• Non-transferable AIDs for simple devices
• Delegated from organizational root AID
• Lightweight key management for resource-constrained devices
• Bulk key generation for device fleets

Credential Issuance:

• QVI uses multi-sig AID for credential signing
• Separate signing keys for operational use
• Pre-rotated keys secured in cold storage
• Transaction Event Logs (TELs) anchored to KEL

Best Practices

Key Hygiene:

• One-time, one-place, one-way: Use keys for single purpose
• Regular rotation schedule based on risk assessment
• Separate signing keys from rotation keys
• Never reuse keys across different AIDs

Security Layering:

• Defense in depth: Multiple security mechanisms
• Threshold structures multiply attack surfaces
• Witness pools provide distributed validation
• Watcher networks enable duplicity detection

Operational Separation:

• Split key generation from event signing infrastructure
• Custodial agents for convenience, controller retains rotation authority
• Partial rotation enables graduated security models
• Delegation trees for organizational scalability

Backup and Recovery:

• Secure backup of root seeds/keys
• Mnemonic phrases for human-memorable recovery
• Pre-rotated keys as compromise recovery mechanism
• Witness receipts provide independent event validation

Integration Considerations

Wallet Integration:

• Keystore management (LMDB in KERIpy, platform-specific in mobile)
• User authentication (passcodes, biometrics)
• Key derivation from user-provided entropy
• Secure enclave usage on supported platforms

Agent Architecture:

• KERIA agent handles KEL management and witness coordination
• Signify client performs signing operations at edge
• Keys never leave client device
• Agent manages operational infrastructure without key access

Witness Coordination:

• OOBI (Out-Of-Band Introduction) for witness discovery
• Receipt collection and threshold verification
• Witness rotation through KEL events
• Mailbox services for asynchronous communication

Registry Integration:

• TEL anchoring to KEL for credential registries
• Management TEL for registry configuration
• VC TEL for individual credential state
• Registrar coordination for distributed registries

Security Considerations

Attack Vectors and Mitigations

Live Key Compromise:

• Attack: Current signing keys stolen while in use
• Mitigation: Pre-rotated keys enable recovery, rotation authority separate from signing

Dead Key Compromise:

• Attack: Compromise of keys after rotation (stale keys)
• Mitigation: Stale keys cannot affect current key state, KEL provides verifiable history

Witness Compromise:

• Attack: Attacker compromises witness infrastructure
• Mitigation: Threshold-based acceptance, multiple independent witnesses, watcher networks

Duplicity Attacks:

• Attack: Controller creates multiple conflicting KELs
• Mitigation: First-seen policy, witness receipts, ambient duplicity detection

Quantum Resistance

KERI's pre-rotation mechanism provides post-quantum security:

• Pre-rotated key digests use one-way hash functions
• Even if quantum computers break current signature schemes, pre-committed digests remain secure
• Enables rotation to quantum-resistant algorithms
• Forward security through cryptographic hiding

Privacy Considerations

Key Correlation:

• Different AIDs use different keys to prevent correlation
• Hierarchical deterministic derivation enables key diversity
• Selective disclosure of keys based on context

Metadata Leakage:

• KEL structure reveals key rotation history
• Witness configuration may reveal organizational relationships
• OOBI resolution can leak discovery patterns
• Mitigation through privacy-preserving protocols and selective disclosure