This architectural separation reflects KERI's modular design philosophy: the keystore focuses exclusively on cryptographic key material protection, while higher-level components handle event logs, credentials, and protocol operations. This separation enables:

• Clear security boundaries between key material and derived data
• Modular replacement of storage backends without affecting protocol logic
• Graduated security policies where key material receives stronger protection than event logs
• Simplified audit of cryptographic operations

Core Components

A KERI keystore manages several categories of cryptographic material:

Private Keys: The keystore's primary responsibility is securing the private keys that provide control authority over AIDs. These include:

• Current signing keys: Active keys used to sign non-establishment events
• Pre-rotated keys: Future rotation keys committed to in previous establishment events
• Delegated keys: Keys for delegated identifiers in hierarchical structures

Derivation Context: To support hierarchical deterministic key generation, the keystore maintains:

• Salt values: Cryptographic randomness used as input to key derivation functions
• Derivation paths: Hierarchical paths for generating multiple keys from a single seed
• Key indices: Tracking which keys in a sequence have been generated and used

Metadata: Supporting information for key management:

• Key identifiers: Mapping between keys and the AIDs they control
• Key state history: Tracking which keys were valid at which points in time
• Threshold configurations: For multi-signature identifiers

Implementation: Hab Architecture

In the Python implementation (KERIpy), the keystore is organized around the Hab (Habitat) abstraction. As described in Document 9:

"A Hab is a keystore for one identifier. It stores key material and all other data associated with a single AID."

This one-to-one relationship between Hab and AID provides:

• Isolation: Each identifier's keys are stored separately
• Scalability: Multiple identifiers can be managed independently
• Security: Compromise of one Hab doesn't affect others

Multiple Habs are organized within a Habery, which serves as a collection manager for keystores. This two-level architecture (Habery containing multiple Habs) enables efficient management of multiple identities while maintaining strong isolation between them.

Data Format

Storage Technology

The reference implementation uses LMDB (Lightning Memory-Mapped Database) as the underlying storage engine. As documented in Document 9:

"The Python implementation in KERIpy, also used by KERIA, uses LMDB to store key material and all other data."

LMDB provides several advantages for keystore implementation:

Performance Characteristics:

• Memory-mapped I/O: Direct memory access without system call overhead
• Zero-copy reads: Data accessed directly from mapped memory
• ACID transactions: Atomic updates with crash recovery
• Concurrent readers: Multiple read operations without blocking

Security Properties:

• File-level encryption: Can be combined with filesystem encryption
• Atomic writes: Prevents partial key material exposure during crashes
• Compact storage: Efficient space utilization for cryptographic primitives

Encryption Layer

The keystore implements encryption-at-rest using a passcode-derived key. According to Document 44:

"The default status a KERI data store is in once it has been created using a passcode; it is by default encrypted."

This locked state is the default security posture, ensuring that:

• No plaintext keys exist on disk
• Passcode required for all operations
• Brute-force resistance through key stretching

Key Derivation Process

KERI keystores support deterministic key generation from a cryptographic seed. As explained in Document 1:

"The salt value, combined with other context including the keystore's aeid (authentication encryption identifier), deterministically generates all key-pairs belonging to an identifier. This means that with the same salt and context, the same keys will always be produced."

This deterministic property enables:

• Key recovery: Regenerating keys from the original salt
• Backup simplicity: Only the salt needs secure backup
• Reproducibility: Testing with known key sequences

Directory Structure

When initialized, a KERI keystore creates three directory structures, as shown in Document 1:

/usr/local/var/keri/ks/{name}   # KERI Keystore (encrypted keys)
/usr/local/var/keri/db/{name}   # KERI Database (KELs, state)
/usr/local/var/keri/reg/{name}  # KERI Credential Store (ACDCs)

This separation reflects the architectural distinction between:

• ks/: Pure keystore functionality (private keys)
• db/: Event log storage (KELs, receipts)
• reg/: Credential registry (issued/received ACDCs)

Field Organization

While the exact internal schema is implementation-specific, keystores typically organize data around:

Per-AID Records:

• AID prefix (identifier)
• Current key pairs (signing keys)
• Next key digests (pre-rotation commitments)
• Threshold configuration (for multi-sig)
• Witness configuration

Cryptographic Primitives:

• Keys encoded in CESR format
• Derivation codes indicating key types
• Qualified primitives with algorithm identifiers

Metadata:

• Creation timestamps
• Last access times
• Key rotation history

Operations

Initialization

Keystore initialization is the first operation in any KERI workflow. The KLI (KERI Command Line Interface) provides the kli init command for this purpose. From Document 1:

kli init --name {keystore_name} \
    --passcode {encryption_credential} \
    --salt {cryptographic_input} \
    --config-dir ./config \
    --config-file keystore_init_config.json

Required Parameters:

• --name: Unique identifier for the keystore (used in directory paths)
• --passcode: Encryption credential protecting keystore contents
• --salt: Cryptographic input for deterministic key generation

Optional Parameters:

• --config-dir: Directory containing configuration files
• --config-file: JSON file with witness and other configuration
• --nopasscode: Development-only flag to skip encryption (insecure)

The initialization process:

1. Creates directory structure at /usr/local/var/keri/
2. Generates encryption key from passcode using key stretching
3. Initializes LMDB database with encrypted storage
4. Stores salt for key derivation
5. Loads witness configuration if provided

Passcode Management

Secure passcode handling is critical for keystore security. Document 4 describes three storage options:

1. Insecure (Development Only):

./scripts/source.sh --insecure

Stores passcode in plaintext on filesystem. Never use in production.

2. macOS Keychain Integration:

./scripts/source.sh --kc

Stores passcode in macOS Keychain with OS-level encryption and access control.

3. 1Password Integration:

./scripts/source.sh --op

Stores passcode in 1Password vault with enterprise-grade security.

The document emphasizes:

"The vLEI ecosystem treats both salt (used to create deterministic public/private key pairs) and passcode as vital components equivalent in importance to private keys."

AID Creation

Once a keystore is initialized, AIDs can be created through inception events. From Document 1:

kli incept --name {keystore_name} \
    --alias {aid_alias} \
    --icount 1 \
    --isith 1 \
    --ncount 1 \
    --nsith 1 \
    --wits {witness_aids} \
    --toad 2 \
    --transferable

This operation:

1. Generates key pairs using the keystore's salt and derivation context
2. Creates inception event with initial keys and configuration
3. Stores private keys in encrypted keystore
4. Publishes event to configured witnesses
5. Returns AID prefix (self-certifying identifier)

The keystore maintains the relationship between:

• The AID prefix (public identifier)
• The controlling private keys (secret material)
• The key state history (rotation events)

Key Rotation

KERI's pre-rotation mechanism requires the keystore to manage both current and future keys. As explained in Document 28:

"With pre-rotation: The cryptographic commitment (a digest of the public keys) for the next key set is embedded within the current key establishment event. The next keys can be generated and secured in advance, separate from the currently active operational keys."

The keystore's role in rotation:

Pre-Rotation Phase:

1. Generate next key pairs during inception or previous rotation
2. Compute key digests for commitment
3. Store next private keys securely (never exposed until rotation)
4. Include digests in current establishment event

Rotation Execution:

1. Retrieve next private keys from keystore
2. Sign rotation event with current keys
3. Expose next public keys in rotation event
4. Generate new next keys for future rotation
5. Update key state in keystore

This process ensures that:

• Current keys can be compromised without affecting rotation capability
• Next keys remain protected until needed
• Rotation authority is cryptographically committed in advance

Multi-Signature Operations

For multi-signature identifiers, the keystore must coordinate with other participants. From Document 18:

"Multi-signature group AIDs require signatures from multiple authorized participants according to defined signing thresholds."

The keystore's responsibilities:

Threshold Configuration:

• Store threshold values (isith, nsith)
• Track which keys belong to which participants
• Maintain participant AID references

Signature Generation:

• Sign events with local keys
• Collect signatures from other participants
• Verify threshold satisfaction before event publication

Coordination:

• Use mailbox services for asynchronous communication
• Handle partial signatures and signature aggregation
• Manage timeout and retry logic

Delegation Operations

For delegated identifiers, the keystore manages the relationship between delegator and delegate. From Document 24:

"Both the delegator and delegate must actively participate in cryptographic operations to establish and maintain the delegation relationship."

Keystore operations for delegation:

Delegate Keystore:

1. Generate delegated AID keys with delegation context
2. Create delegated inception event referencing delegator
3. Store delegation proof (delegator's seal)
4. Maintain delegation chain for verification

Delegator Keystore:

1. Create delegation seal for delegate's event
2. Anchor seal in delegator's KEL
3. Store delegate references for management
4. Support delegation revocation if needed

Access Control

The keystore implements access control through:

Passcode Verification:

• All operations require passcode
• Failed attempts may trigger lockout
• Passcode changes require re-encryption

Operation Authorization:

• Only authorized operations can access keys
• Read-only operations for verification
• Write operations for signing and rotation

Audit Logging:

• Track key access attempts
• Log signing operations
• Monitor for suspicious activity

Usage Context

Protocol Integration

The keystore integrates with multiple KERI protocols:

KERI Core Protocol:

• Provides keys for signing key events
• Supports establishment events (inception, rotation)
• Enables interaction events for data anchoring

ACDC Protocol:

• Signs ACDC credentials during issuance
• Provides keys for IPEX (Issuance and Presentation Exchange)
• Supports selective disclosure operations

OOBI Protocol:

• Signs OOBI (Out-Of-Band Introduction) messages
• Authenticates discovery information
• Enables secure bootstrapping

Lifecycle Management

The keystore follows a defined lifecycle:

Creation Phase:

1. Initialize with passcode and salt
2. Configure witnesses and thresholds
3. Generate initial AIDs

Operational Phase:

1. Sign events and credentials
2. Perform key rotations
3. Manage delegations
4. Handle multi-sig coordination

Maintenance Phase:

1. Backup salt and configuration
2. Update passcode if needed
3. Rotate keys on schedule
4. Monitor for compromise

Recovery Phase:

1. Restore from salt backup
2. Regenerate keys deterministically
3. Resync with witnesses
4. Verify key state consistency

Deployment Patterns

Local Development:

• Single keystore on developer machine
• Insecure passcode storage acceptable
• Used for testing and learning

Production Individual:

• Keystore on personal device
• Passcode in OS keychain or password manager
• Regular backups of salt

Production Organization:

• Multiple keystores for different roles
• Hardware security modules for high-value keys
• Distributed multi-sig for critical operations

Cloud Agent (KERIA):

• Keystore runs in cloud service
• Accessed via REST API
• Supports multiple users/tenants

Related Structures

The keystore interacts with several related data structures:

KEL (Key Event Log):

• Keystore provides keys to sign KEL events
• KEL records key state changes
• Keystore verifies KEL consistency

KERL (Key Event Receipt Log):

• Keystore signs events that witnesses receipt
• KERL provides distributed verification
• Keystore validates witness receipts

TEL (Transaction Event Log):

• Keystore signs credential issuance/revocation events
• TEL tracks credential state
• Keystore anchors TEL to KEL

Wallet:

• Wallet contains keystore plus additional databases
• Provides user interface to keystore operations
• Manages credentials and presentations

Security Considerations

Threat Model:

• Physical access: Encryption protects against disk theft
• Memory attacks: Keys only decrypted when needed
• Network attacks: Keys never transmitted
• Malware: OS-level protections and sandboxing

Best Practices:

1. Strong passcodes: Use generated passphrases, not user-chosen passwords
2. Secure salt storage: Backup salt separately from keystore
3. Regular rotation: Rotate keys on schedule, not just after compromise
4. Minimal exposure: Decrypt keys only for signing operations
5. Audit logging: Monitor all keystore access

Recovery Planning:

• Salt backup: Essential for key regeneration
• Passcode recovery: Use password manager or secure vault
• Witness coordination: Ensure witnesses maintain KEL copies
• Delegation chains: Document delegation relationships

Implementation Variations

KERIpy (Python):

• LMDB storage backend
• Command-line interface (KLI)
• Used in KERIA cloud agents

KERIox (Rust):

• Alternative storage backends
• Performance-optimized
• Embedded systems support

SignifyTS (TypeScript):

• Browser-based keystores
• IndexedDB storage
• Web Crypto API integration

Hardware Wallets:

• Dedicated security chips
• Air-gapped operation
• Physical confirmation required

Each implementation maintains the same security properties while adapting to platform constraints and use cases.

• Generate salts using cryptographically secure random number generators
• Store salts separately from keystores (different backup location)
• Never reuse salts across keystores
• Document salt format and derivation algorithm

Derivation Context: The keystore must maintain consistent derivation context including:

• Salt value
• Derivation algorithm (e.g., HKDF, PBKDF2)
• Key index/path for HD derivation
• Algorithm parameters (iterations, hash function)

Changing any context parameter will generate different keys, breaking recovery.

Key Rotation Implementation

Pre-rotation requires careful state management:

State Transitions:

1. Pre-rotation: Generate next keys, store privately, publish digests
2. Rotation: Expose next keys, sign with current keys, generate new next keys
3. Post-rotation: Update current keys, archive old keys

Timing Considerations:

• Next keys must be generated before current keys are compromised
• Rotation events must be signed with current keys (not next keys)
• Old keys should be retained for historical verification

Partial Rotation: Support partial rotation where only some keys are rotated:

• Track which keys are current vs. next
• Support mixed key sets during transition
• Maintain threshold satisfaction during rotation

Multi-Signature Coordination

Multi-sig keystores require additional coordination logic:

Signature Collection:

• Implement timeout mechanisms for slow participants
• Support partial signature storage and aggregation
• Verify threshold satisfaction before event publication
• Handle participant unavailability gracefully

Mailbox Integration: Use witness mailboxes for asynchronous communication:

• Poll mailboxes for pending signature requests
• Store partial signatures until threshold met
• Notify participants of completion

Delegation Support

Delegated keystores must maintain delegation chains:

Delegation Metadata:

• Store delegator AID reference
• Maintain delegation seal from delegator
• Track delegation depth for nested delegations
• Support delegation revocation

Verification: Delegated keystores must verify:

• Delegator's KEL contains delegation seal
• Delegation seal matches delegate's inception event
• Delegator's keys were valid at delegation time

Backup and Recovery

Essential Backups:

1. Salt: Required for key regeneration
2. Passcode: Required for keystore decryption
3. Configuration: Witness lists, thresholds, delegation chains

Recovery Process:

1. Restore salt and passcode from backup
2. Regenerate keys using original derivation context
3. Resync KEL from witnesses
4. Verify key state consistency
5. Resume normal operations

Backup Security:

• Encrypt backups separately from keystore
• Store backups in different physical locations
• Test recovery process regularly
• Document recovery procedures

Performance Optimization

Caching Strategies:

• Cache decrypted keys for active signing sessions
• Implement key expiration to limit exposure
• Use memory pools to avoid allocation overhead
• Batch signature operations when possible

Concurrent Access:

• Support multiple readers for verification operations
• Serialize write operations (signing, rotation)
• Use read-write locks for efficiency
• Implement connection pooling for LMDB

Platform-Specific Considerations

Desktop Applications:

• Integrate with OS keychain (macOS Keychain, Windows Credential Manager)
• Support hardware security modules (HSM, TPM)
• Implement secure memory allocation
• Handle system sleep/wake cycles

Mobile Applications:

• Use platform secure storage (iOS Keychain, Android Keystore)
• Implement biometric authentication
• Handle app backgrounding/foregrounding
• Minimize battery impact

Browser Extensions:

• Use IndexedDB for storage
• Leverage Web Crypto API
• Implement content security policies
• Handle extension updates gracefully

Cloud Agents (KERIA):

• Implement multi-tenancy with keystore isolation
• Use hardware security modules for high-value keys
• Implement rate limiting and abuse prevention
• Support keystore migration between instances

Testing Requirements

Unit Tests:

• Key generation and derivation
• Encryption and decryption
• Signature generation and verification
• State transitions (inception, rotation)

Integration Tests:

• Multi-sig coordination
• Delegation workflows
• Witness interaction
• Recovery procedures

Security Tests:

• Brute-force resistance
• Memory leak detection
• Timing attack resistance
• Fault injection

Compliance and Standards

Cryptographic Standards:

• Use NIST-approved algorithms
• Support post-quantum algorithms where specified
• Implement algorithm agility for future upgrades
• Document algorithm choices and parameters

Key Management Standards:

• Follow NIST SP 800-57 for key lifecycle
• Implement FIPS 140-2/3 where required
• Support HSM integration for regulated environments
• Maintain audit logs for compliance

Error Handling

Common Error Scenarios:

• Incorrect passcode (implement lockout after N attempts)
• Corrupted keystore (attempt recovery, fail safely)
• Missing salt (cannot recover, require backup)
• Witness unavailability (queue operations, retry)
• Threshold not met (wait for participants, timeout)

Error Recovery:

• Implement transaction rollback for failed operations
• Maintain keystore consistency during errors
• Log errors for debugging
• Provide clear error messages to users

Migration and Upgrades

Version Compatibility:

• Support reading older keystore formats
• Implement automatic migration on first access
• Maintain backward compatibility for recovery
• Document breaking changes

Algorithm Upgrades:

• Support multiple encryption algorithms
• Implement gradual migration to new algorithms
• Maintain old keys for historical verification
• Document upgrade procedures