Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 99 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
KERIA (KERI Agent in the cloud) is a multi-tenant cloud-based agent implementation for the KERI protocol that provides agency services for managing Autonomic Identifiers (AIDs), credentials, and key event operations while maintaining strict separation of private key material from cloud infrastructure through edge-based signing.
KERIA (KERI Agent in the cloud) is the Python-based cloud agent implementation for the KERI protocol, originally split from the KERIpy core codebase to provide dedicated cloud-based agency services. The implementation is built on Python 3.12.1+ and requires libsodium 1.0.18+ as a critical cryptographic dependency.
KERIA implements a multi-tenant agent architecture where multiple users can share infrastructure while maintaining cryptographic isolation. The fundamental design principle is that all client tasks and calls must be signed at the edge (client-side) rather than within the hosted KERIA instance, ensuring that the cloud agent never has access to private key material.
The implementation is maintained by the WebOfTrust organization with active development tracked through GitHub Actions CI/CD and Codecov integration. Current maintainers include Fergal O'Connor, Daniel Lenksjö, and Kent Bull, with the project following a 2-of-3 approval threshold for pull requests.
KERIA exposes three distinct HTTP endpoints on separate network interfaces, each serving specific security boundaries:
1. Boot Interface (default port 3903)
KERIA's fundamental security principle is separation of signing authority from operational infrastructure. Private keys NEVER exist on KERIA servers - all signing operations occur client-side in Signify libraries. KERIA stores only encrypted key material with decryption keys held exclusively by clients.
The separation of Boot, Admin, and Protocol interfaces enables network-level security controls. Production deployments should:
Each KERIA agent is a Hab (keystore) instance managing one AID. The Agency component maintains the authoritative database of all agents, enabling recovery after restarts. The KERIA_RELEASER_TIMEOUT controls idle agent shutdown for resource management in multi-tenant deployments.
KERIA implements cooperative delegation where:
This enables clients to "fire" KERIA by rotating keys without requiring KERIA cooperation.
KERIA handles asynchronous multi-sig through:
Known Issue: Partial thresholds (2-of-3) cause KEL desynchronization for non-signing members. Workaround: use full participation thresholds (3-of-3).
KERIA uses LMDB for:
LMDB provides memory-mapped access for performance while maintaining ACID properties.
KERIA coordinates with witness networks through:
2. Admin Interface (default port 3901)
3. KERI Protocol Interface (default port 3902)
This separation allows network-level security controls where administrators can expose interfaces to different network zones based on operational requirements.
While KERIA never possesses private keys, it handles critical operational tasks:
Key Index Storage: Stores key indexes retrieved by Signify clients on boot up
Delegated AID Creation: Creates KERI AIDs delegated from the edge AID
KEL Management: Manages Key Event Logs for edge AIDs, maintaining the verifiable history of key events
ACDC Operations: Creates, stores, issues, revokes, presents, and receives ACDCs (Authentic Chained Data Containers)
Cloud Mailbox Function: Acts as a cloud mailbox to send and receive KERI and ACDC messages, including:
Credential Management: Implements advanced credential searching using SAD path language with pagination support, creating indices using CESRSuber for efficient credential querying
The Message Router serves as the entry point for external KERI protocol messages, handling:
The Agency functions as the central repository for agent provisioning and management:
/boot requests) to provision new agentsThe API Handler processes agent-specific API requests via /agent endpoints:
Individual Agents operate on behalf of Signify clients while maintaining security boundaries:
# Create Python virtual environment
python3 -m venv venv
# Activate environment
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Launch agent
keria start --config-dir scripts --config-file demo-witness-oobis
The startup command references a configuration file that configures witness connections via Out-Of-Band Introductions (OOBIs).
# Build KERIA container image
make build-keria
KERIA supports dual configuration approaches for different deployment environments:
Environment Variable Configuration:
JSON Configuration File Approach:
Provides structured configuration for complex deployments:
# Relative path invocation
keria start --config-dir scripts --config-file keria
# Absolute path invocation
keria start --config-dir /absolute/path --config-file /absolute/config
JSON structure requires:
dt fields) for configuration validationEstablishing Signify-KERIA connection requires a three-step handshake:
Step One: Generate Client AID
The Signify Client generates the Client AID as a transferable AID with:
Key generation algorithm:
signify:controller00 and signify:controller01Step Two: Initialize Agent Worker
The signed inception event is provided out-of-band to KERIA through the Boot interface. The HTTP request must be signed by the Client AID using Signify Request Authentication.
KERIA creates the Agent AID as a delegated identifier from the Client AID:
Step Three: Delegation Approval
Client AID creates interaction event with seal anchoring Agent AID's inception event, completing the cooperative delegation.
KERIA supports passcode rotation for security maintenance:
This enables periodic security updates without changing the Client AID itself.
KERIA provides comprehensive credential lifecycle management:
Credential Issuance:
# Issue credential using KERIA API
response = client.credentials().issue(
issuer_aid=issuer_prefix,
schema_said=schema_said,
recipient_aid=recipient_prefix,
attributes=credential_data
)
Credential Presentation:
# Present credential to verifier
response = client.credentials().present(
holder_aid=holder_prefix,
credential_said=credential_said,
verifier_aid=verifier_prefix
)
Credential Revocation:
# Revoke credential
response = client.credentials().revoke(
issuer_aid=issuer_prefix,
credential_said=credential_said
)
KERIA handles asynchronous multi-signature operations:
This enables distributed signing across geographically separated controllers.
KERIA includes an interceptor class that enables event propagation from the cloud agent to other backend processes and web services. This component:
SignifyTS (TypeScript): Browser and Node.js client for KERIA
SignifyPy (Python): Python client library for KERIA
KERIA was originally part of KERIpy (version 1.1.32+) and maintains close integration:
KERI-ox (Rust): Rust implementation of KERI protocol
KERI-ml (Swift): Swift implementation for iOS/macOS
Signify Browser Extension: Browser-based wallet for KERIA
KERIA serves as the QVI (Qualified vLEI Issuer) infrastructure in the GLEIF vLEI ecosystem:
KERIA's security model is based on zero-knowledge architecture:
KERIA uses LMDB (Lightning Memory-Mapped Database) for persistent storage:
KERIA coordinates with witness networks:
Resource Isolation: Each agent operates in isolated context with dedicated storage
Scaling: KERIA supports horizontal scaling through multiple instances
Load Balancing: Can distribute agents across multiple KERIA instances
Timeout Management: KERIA_RELEASER_TIMEOUT controls idle agent shutdown for resource management
KERIA includes comprehensive testing:
Multisig State Synchronization (GitHub issue #316): In multisig configurations with partial thresholds (e.g., 2-of-3), non-signing members are not notified of completed events, causing KEL desynchronization. Current workaround requires full participation thresholds (3-of-3).
NI2I Operator Bug (GitHub issue #1040): Credential creation with NI2I (Not-Issuer-To-Issuee) operator hangs indefinitely with no workaround available.
Network Security: Separate Boot interface from public interfaces using network policies
TLS/SSL: Use reverse proxy (nginx, traefik) for HTTPS termination
Monitoring: Integrate with logging and monitoring systems via interceptor
Backup: Regular backup of LMDB databases for disaster recovery
Witness Configuration: Use production witness networks with appropriate TOAD thresholds
Configuration Management: Use JSON configuration files for complex deployments
KERIA is used in production for GLEIF vLEI ecosystem:
This demonstrates KERIA's production readiness for enterprise identity infrastructure.
Production deployments should use JSON configuration files rather than environment variables for:
JSON configs support ISO 8601 timestamps for validation and versioning.
KERIA testing requires:
kli witness demo or production witnessesKERIA is production-ready as demonstrated by GLEIF vLEI ecosystem:
Browser Extension: Signify browser extension connects to KERIA for cloud operations while maintaining client-side signing
Mobile Apps: Veridian wallet (Cardano Foundation) uses KERIA for backend operations
Server Applications: SignifyPy provides Python-native API for server-side KERIA integration
Regulatory Systems: reg-pilot demonstrates KERIA integration with regulatory reporting APIs using vLEI credentials