2. Admin Interface (default port 3901)

• Provides REST API for command and control operations from Signify clients
• All requests must be signed by the Client AID using Signify Request Authentication
• All responses are signed by the Agent AID
• Handles AID creation and management, credential operations, key state queries

3. KERI Protocol Interface (default port 3902)

• Implements CESR over HTTP for KERI protocol interactions
• Enables communication with witnesses, watchers, and other KERI agents
• Handles external credential exchange and verification operations

This separation allows network-level security controls where administrators can expose interfaces to different network zones based on operational requirements.

Core Agent Responsibilities

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:

• Interacting with witnesses for key event witnessing
• Exchanging messages with other KERI agents
• Handling asynchronous message routing for multi-signature coordination

Credential Management: Implements advanced credential searching using SAD path language with pagination support, creating indices using CESRSuber for efficient credential querying

Message Router Component

The Message Router serves as the entry point for external KERI protocol messages, handling:

• Multi-signature coordination messages with asynchronous waiting for signature responses
• Credential revocation notifications
• Routing incoming responses to appropriate agents
• Seamless interaction with all KERI clients, not just Signify-based clients

Agency Component

The Agency functions as the central repository for agent provisioning and management:

• Receives API requests (/boot requests) to provision new agents
• Maintains authoritative database of all existing agents
• Ensures agent state can be recovered after service restarts
• Maintains mappings between managed AIDs and specific agencies handling those identifiers

API Handler Component

The API Handler processes agent-specific API requests via /agent endpoints:

• Creates new identifiers
• Receives and manages credentials
• Performs identifier-related operations
• Security requirement: All API calls must include signatures in client headers
• Interactions are persisted in agent-specific databases

Individual Agents

Individual Agents operate on behalf of Signify clients while maintaining security boundaries:

• Do not possess client secrets or private keys
• Handle operational aspects of maintaining AIDs' KELs and ACDCs
• Ensure availability of identity infrastructure
• Each agent is an instance of a keystore (Hab) running in the KERIA agent server

Installation & Setup

Prerequisites

• Python 3.12.1 or higher as the runtime environment
• libsodium 1.0.18+ as a critical cryptographic dependency

Source-Based Installation

# 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).

Docker-Based Deployment

# Build KERIA container image
make build-keria

Configuration Architecture

KERIA supports dual configuration approaches for different deployment environments:

Environment Variable Configuration:

• KERIA_CURLS: Service Endpoint Location URLs creating Endpoint Role Authorizations and Location Scheme records on startup
• KERIA_IURLS: Introduction URLs (OOBIs) resolved on startup for bootstrapping connection to KERI infrastructure
• KERIA_DURLS: Data OOBI URLs resolved on startup, typically pointing to ACDC credential schemas
• KERIA_RELEASER_TIMEOUT: Idle timeout before agent shutdown (default: 86400 seconds / 1 day)

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:

• Root object matching agent name (default "keria")
• ISO 8601 timestamps (dt fields) for configuration validation
• Configuration sections for witnesses, OOBIs, and service endpoints

Usage & API

Agent Worker Initialization Protocol

Establishing 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:

• Single signing key
• Single rotation key (pre-rotated)
• The Client AID serves as the delegator in the delegation relationship

Key generation algorithm:

1. Prepend 128-bit random salt derivation code ('0A') plus blank qualified base64 character ('A') to the 21-character passcode
2. Stretch passcode using Argon2 to generate Ed25519 private key from provided "tier" and paths signify:controller00 and signify:controller01
3. Use qualified base64 of signing public key and Blake3 digest of rotation public key in inception event

Step 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:

• Agent AID inception event includes delegation seal pointing to Client AID's inception event
• Agent AID uses same witness configuration as Client AID
• Delegation must be approved by Client AID through interaction event

Step Three: Delegation Approval

Client AID creates interaction event with seal anchoring Agent AID's inception event, completing the cooperative delegation.

Passcode Rotation

KERIA supports passcode rotation for security maintenance:

1. Client generates new passcode and derives new key pairs
2. Client creates rotation event for Client AID with new keys
3. Client submits rotation event to KERIA
4. KERIA updates stored key indexes
5. Old passcode becomes invalid

This enables periodic security updates without changing the Client AID itself.

Credential Operations

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
)

Multi-Signature Coordination

KERIA handles asynchronous multi-signature operations:

1. First signer submits partially signed event
2. KERIA stores event in escrow
3. Subsequent signers retrieve and add signatures
4. Once threshold met, KERIA processes complete event
5. All participants notified of completion

This enables distributed signing across geographically separated controllers.

Interceptor Component

KERIA includes an interceptor class that enables event propagation from the cloud agent to other backend processes and web services. This component:

• Pushes events occurring inside the cloud agent to external systems
• Similar to notifier class but specifically targets web service integration
• Enables integration with external monitoring and analytics systems

Related Implementations

Signify Client Libraries

SignifyTS (TypeScript): Browser and Node.js client for KERIA

• Implements edge-based signing
• Manages key generation client-side
• Communicates with KERIA via CESR-encoded messages
• Version 0.3.0-rc1 tested with KERIA 0.3.0

SignifyPy (Python): Python client library for KERIA

• Equivalent functionality to SignifyTS
• Used in server-side applications
• Provides Python-native API for KERIA operations

KERIpy Core Implementation

KERIA was originally part of KERIpy (version 1.1.32+) and maintains close integration:

• Shares cryptographic primitives
• Uses same LMDB storage engine
• Compatible with KLI (KERI Command Line Interface)
• Witnesses run on KERIpy 1.2.6+

Alternative Agent Implementations

KERI-ox (Rust): Rust implementation of KERI protocol

• Provides alternative to Python-based agents
• Focus on performance and memory safety
• Compatible with KERIA through KERI protocol

KERI-ml (Swift): Swift implementation for iOS/macOS

• Mobile-focused agent implementation
• Integrates with Apple ecosystem
• Can interact with KERIA agents

Browser Extension Integration

Signify Browser Extension: Browser-based wallet for KERIA

• Manages AIDs directly in browser
• Connects to KERIA agents for cloud operations
• Provides MetaMask-like experience for KERI
• Implements signing associations for website authentication

vLEI Ecosystem Integration

KERIA serves as the QVI (Qualified vLEI Issuer) infrastructure in the GLEIF vLEI ecosystem:

• Issues Legal Entity vLEI Credentials
• Manages OOR (Official Organizational Role) credentials
• Handles ECR (Engagement Context Role) credentials
• Integrates with Sally verifier for credential presentation
• Supports vLEI Reporting API interactions

Implementation Notes

Security Architecture

KERIA's security model is based on zero-knowledge architecture:

1. Private keys never transmitted: All signing operations occur client-side
2. Encrypted storage: Private keys stored encrypted with keys held only by client
3. Signed requests: All API calls include cryptographic signatures
4. Signed responses: All KERIA responses signed by Agent AID
5. Delegation model: Agent AID delegated from Client AID, enabling revocation

Storage Implementation

KERIA uses LMDB (Lightning Memory-Mapped Database) for persistent storage:

• Each agent has dedicated database
• Stores KELs, credentials, and operational state
• Memory-mapped for performance
• ACID transaction support
• Compact data storage

Witness Integration

KERIA coordinates with witness networks:

• Sends key events to configured witnesses
• Collects witness receipts
• Maintains KERL (Key Event Receipt Log)
• Implements KAACE (KERI Agreement Algorithm for Control Establishment)
• Supports TOAD (Threshold of Accountable Duplicity) configuration

Multi-Tenancy Considerations

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

Testing Infrastructure

KERIA includes comprehensive testing:

• pytest for unit tests
• Integration tests with witness networks
• E2E tests with Signify clients
• Docker Compose configurations for test environments
• CI/CD through GitHub Actions

Known Issues

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.

Production Deployment Considerations

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

vLEI Production Usage

KERIA is used in production for GLEIF vLEI ecosystem:

• GLEIF: Uses KERIpy 1.1.30 for root authority
• QVIs: Use KERIA 0.3.0 for credential issuance
• Witnesses: Run KERIpy 1.2.8-rc2
• Integration: SignifyTS 0.3.0-rc1 for client operations

This demonstrates KERIA's production readiness for enterprise identity infrastructure.

• Sending key events to configured witnesses
• Collecting witness receipts
• Maintaining KERL (KEL + receipts)
• Implementing KAACE consensus algorithm
• Supporting configurable TOAD thresholds

Configuration Management

Production deployments should use JSON configuration files rather than environment variables for:

• Complex witness configurations
• Multiple service endpoints
• Schema OOBI specifications
• Timeout and resource limits

JSON configs support ISO 8601 timestamps for validation and versioning.

Testing Requirements

KERIA testing requires:

• Witness network: kli witness demo or production witnesses
• vLEI-server: For schema and credential OOBI resolution
• Signify clients: For end-to-end workflow testing
• Docker Compose: For integration test environments

Production Deployment Checklist

1. Network Security: Isolate Boot interface, use TLS for Admin/Protocol
2. Witness Configuration: Use production witnesses with appropriate TOAD
3. Monitoring: Integrate interceptor with logging/monitoring systems
4. Backup: Regular LMDB database backups
5. Resource Limits: Configure KERIA_RELEASER_TIMEOUT for multi-tenancy
6. Load Balancing: Distribute agents across multiple KERIA instances
7. Configuration: Use JSON files for complex deployments

vLEI Production Usage

KERIA is production-ready as demonstrated by GLEIF vLEI ecosystem:

• Version: KERIA 0.3.0 with SignifyTS 0.3.0-rc1
• Witnesses: KERIpy 1.2.8-rc2
• Use Case: QVI credential issuance infrastructure
• Scale: Multiple QVIs issuing Legal Entity, OOR, and ECR credentials

Performance Considerations

• LMDB: Memory-mapped storage provides high-performance reads
• Asynchronous Operations: Non-blocking I/O for witness coordination
• Multi-Tenancy: Horizontal scaling through multiple instances
• Resource Management: Idle timeout prevents resource exhaustion

Integration Patterns

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