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

• Don't block on all witnesses responding
• Accept event when threshold receipts received
• Continue collecting additional receipts for redundancy
• Implement timeout and retry logic

Witness Rotation: When rotating witness set:

• Use br (backer remove) and ba (backer add) fields
• Ensure new witnesses can access KEL history
• Maintain threshold during transition
• Old witnesses should continue receipting until transition complete

Error Handling

Key Compromise Detection: Implement duplicity detection:

• Monitor for conflicting KEL versions
• Use first-seen policy for event acceptance
• Maintain watcher network for ambient verification
• Alert on detected duplicity

Recovery Procedures: For key compromise:

1. Immediately rotate using pre-rotated keys
2. Generate new pre-rotated keys for next rotation
3. Update witness configuration if witnesses compromised
4. Notify relying parties of rotation
5. Investigate compromise source

Performance Optimization

Key Generation: Pre-generate key pairs during idle time to avoid latency during operations. Maintain pool of ready-to-use keys.

Signature Verification: Cache verified key states to avoid re-walking KEL for every verification. Invalidate cache on new events.

Witness Coordination: Use connection pooling and parallel requests to witnesses. Implement circuit breakers for unresponsive witnesses.

Platform-Specific Considerations

Mobile Platforms:

• Use platform secure enclaves (iOS Secure Enclave, Android Keystore)
• Implement biometric authentication for key access
• Handle app backgrounding and key material in memory
• Implement secure backup to cloud with encryption

Server Platforms:

• Use HSMs for high-value keys
• Implement key ceremony procedures for root key generation
• Use TEEs (SGX, TrustZone) for key operations
• Implement audit logging for all key operations

IoT Devices:

• Consider non-transferable AIDs for resource-constrained devices
• Implement lightweight key storage
• Use delegation from more capable devices
• Plan for device compromise and replacement

Testing Requirements

Key Management Tests:

• Test key generation with various entropy sources
• Verify pre-rotation commitment and revelation
• Test multi-signature threshold enforcement
• Verify partial rotation logic
• Test key compromise recovery scenarios
• Verify witness coordination and receipt collection
• Test delegation and recovery mechanisms

Security Tests:

• Penetration testing of key storage
• Timing attack resistance
• Side-channel attack resistance
• Fuzzing of key event parsing
• Duplicity detection verification