Key Features & Capabilities

Multi-Tenant Agent Architecture

KERIA implements a multi-tenant server architecture where a single KERIA instance can host multiple independent agents, each serving different controllers. This design enables:

• Scalable cloud deployment: One KERIA server can serve hundreds or thousands of independent identity controllers
• Isolated keystores: Each agent maintains cryptographically isolated storage using separate LMDB databases
• Independent witness configurations: Different agents can use different witness pools and threshold configurations
• Per-agent authorization: Each agent has its own Agent AID that participates in cooperative delegation with the Client AID

Three-Interface Service Model

KERIA-agents are accessed through three distinct HTTP interfaces, each serving specific security boundaries:

1. Boot Interface (default port 3903): Handles initial agent provisioning through the /boot endpoint. This interface:

• Accepts signed inception events for new Client AIDs
• Creates the delegated Agent AID relationship
• Can be disabled entirely in static worker mode
• Should be restricted to internal infrastructure in production

2. Admin Interface (default port 3901): Provides the REST API for command and control operations from Signify clients. All requests must:

• Include signatures from the Client AID in request headers
• Use the KRAM (KERI Request Authentication Method) protocol
• Receive responses signed by the Agent AID
• Support operations like AID creation, credential management, and key state queries

3. KERI Protocol Interface (default port 3902): Implements CESR over HTTP for protocol-level interactions:

• Communicates with witnesses, watchers, and other KERI infrastructure
• Handles multi-signature coordination messages
• Routes credential revocation notifications
• Enables asynchronous message exchange through mailbox functionality

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

Cooperative Delegation Model

The KERIA-agent implements KERI's cooperative delegation mechanism, creating a Client AID (delegator) to Agent AID (delegate) relationship:

• Client AID: Controlled directly by the user via a bran (passcode-derived seed), retains rotation authority
• Agent AID: Delegated identifier managed by the KERIA service, has signing authority for operational tasks
• Cooperative operations: All establishment events require participation from both Client and Agent AIDs
• Security guarantee: The agent cannot rotate keys or transfer control without client participation

This model enables custodial rotation patterns where users can "fire" a custodial agent at any time by rotating to new keys, even without the agent's cooperation, because the client retains exclusive rotation authority.

Key Event Log Management

Each KERIA-agent maintains complete KEL (Key Event Log) infrastructure:

• KEL storage: Persistent storage of all key events for managed AIDs
• Witness coordination: Automatic submission of events to configured witnesses for receipting
• KERL construction: Maintains Key Event Receipt Logs including witness signatures
• Event validation: Cryptographic verification of event signatures and hash chains
• Duplicity detection: Monitors for conflicting events indicating potential compromise

ACDC Credential Operations

KERIA-agents provide comprehensive ACDC (Authentic Chained Data Container) credential management:

Issuance Operations:

• Create and sign credential issuance events
• Anchor credentials to TEL (Transaction Event Log) registries
• Support graduated disclosure variants (compact, partial, selective)
• Implement IPEX (Issuance and Presentation Exchange) protocol for credential exchange

Storage and Retrieval:

• Persistent credential storage in agent keystore
• Advanced searching using SAD path language with pagination
• Indexing using CESRSuber for efficient queries
• Support for tracking issued credentials by issuers

Revocation Management:

• TEL-based revocation state tracking
• Registry management for credential lifecycle
• Support for blinded revocation registries
• Revocation event anchoring to KELs

Mailbox and Asynchronous Messaging

KERIA-agents implement mailbox functionality for asynchronous communication:

• Store-and-forward: Messages can be delivered when recipients are offline
• End role authorization: Explicit authorization for mailbox access
• Multi-signature coordination: Enables asynchronous multisig workflows
• Notification system: Server-sent events for real-time updates to connected clients

State Notification System

KERIA-agents provide state notifications using plain SADs (Self-Addressing Data structures):

• Key state notifications: Updates on key state changes
• Transaction state notifications: Updates on TEL state changes
• Credential state notifications: Updates on credential issuance/revocation
• Event streaming: Real-time notification delivery to connected Signify clients

Installation & Setup

Docker Deployment

KERIA-agents are typically deployed using Docker containers. The standard deployment pattern involves:

1. Pull KERIA Image:

docker pull gleif/keria:latest

2. Configuration File: Create a JSON configuration file specifying:

• Witness OOBIs for the agent to use
• Network interface bindings for the three service interfaces
• Database paths for LMDB storage
• Logging configuration

3. Start KERIA Server:

keria start --config-dir /path/to/config --config-file keria --loglevel INFO

For development and testing, Document 3 demonstrates launching bank-specific KERIA instances:

docker run -d --name bank_1_keria \
  -p 3901:3901 -p 3902:3902 -p 3903:3903 \
  ronakseth96/keria:TestBank_1

Local Development Setup

For local development without Docker:

1. Install KERIpy:

pip install keripy==1.1.32

2. Initialize Witness Network (for testing):

kli witness demo

3. Start KERIA:

keria start --config-dir ./scripts --config-file keria --loglevel INFO

Agent Provisioning

Once KERIA is running, agents are provisioned through the Boot Interface using the SKRAP (Signify/KERIA Request Authentication Protocol) initialization process:

Step 1: Generate Client AID (client-side using Signify):

import { randomPasscode, SignifyClient, Tier } from 'signify-ts';

const bran = randomPasscode();
const client = new SignifyClient(
  'http://keria:3901',  // Admin URL
  bran,
  Tier.low,
  'http://keria:3903'   // Boot URL
);

Step 2: Boot Agent:

await client.boot();

This creates the Client AID and submits the signed inception event to the Boot Interface.

Step 3: Connect and Create Agent AID:

await client.connect();

This establishes the cooperative delegation relationship, creating the Agent AID as a delegate of the Client AID.

Usage & API

Creating AIDs

KERIA-agents create new AIDs through the Admin Interface API:

const result = await client.identifiers().create('myAlias', {
  toad: 3,  // Threshold of Accountable Duplicity
  wits: [   // Witness AIDs
    'BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha',
    'BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM',
    'BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX'
  ]
});

const op = await result.op();
await client.operations().wait(op);
const aid = await client.identifiers().get('myAlias');

The agent handles:

• Generating the inception event
• Submitting to configured witnesses
• Collecting witness receipts
• Storing the KEL in the agent's keystore

Authorizing Agent Operations

Clients must explicitly authorize the Agent AID to act on their behalf using end roles:

const result = await client.identifiers().addEndRole(
  'myAlias',           // Client AID alias
  'agent',             // Role type
  agentAID,            // Agent AID prefix
  timestamp            // ISO-8601 timestamp
);

const op = await result.op();
await client.operations().wait(op);

This creates an interaction event in the Client AID's KEL that explicitly grants the Agent AID permission to perform operations.

Credential Issuance

KERIA-agents support full ACDC credential issuance workflows:

1. Create Registry:

const registryResult = await client.registries().create({
  name: 'myAlias',
  registryName: 'vLEI'
});

const regOp = await registryResult.op();
await client.operations().wait(regOp);

2. Issue Credential:

const credentialData = {
  LEI: '254900OPPU84GM83MG36'
};

const result = await client.credentials().issue(
  'myAlias',
  registryName,
  schemaId,
  recipientAID,
  credentialData
);

const credOp = await result.op();
await client.operations().wait(credOp);

The agent:

• Creates the ACDC structure with SAIDs
• Anchors the issuance to the TEL registry
• Stores the credential in the agent's database
• Makes it available for IPEX presentation

OOBI Resolution

KERIA-agents resolve OOBIs (Out-Of-Band Introductions) to discover and verify remote AIDs:

const oobi = 'http://witness:5642/oobi/EABc123.../witness/EBBd456...';
const result = await client.oobis().resolve(oobi, 'remoteAlias');

const oobiOp = await result.op();
await client.operations().wait(oobiOp);

The agent:

• Fetches the remote AID's KEL from the specified endpoint
• Verifies cryptographic integrity
• Stores the KEL for future verification
• Establishes the AID-to-endpoint mapping

Key Rotation

KERIA-agents participate in key rotation through the cooperative delegation model:

const result = await client.identifiers().rotate('myAlias');
const rotOp = await result.op();
await client.operations().wait(rotOp);

The rotation process:

1. Client generates new key pairs at the edge
2. Client creates and signs rotation event
3. Agent receives signed event
4. Agent submits to witnesses
5. Agent collects receipts and updates KEL

Critically, the agent cannot initiate rotation without client participation, preserving the client's ultimate control authority.

State Queries

KERIA-agents provide key state queries:

const keyState = await client.keyStates().get(aidPrefix);

console.log('Sequence number:', keyState.s);
console.log('Current keys:', keyState.k);
console.log('Next key digests:', keyState.n);
console.log('Witnesses:', keyState.b);

This retrieves the current authoritative key state from the agent's KEL storage.

Related Implementations

Signify Client Libraries

KERIA-agents are designed to work with Signify client libraries that implement edge-based signing:

SignifyTS: TypeScript/JavaScript implementation for:

• Browser-based applications
• Node.js server applications
• React Native mobile apps
• Electron desktop applications

SignifyPy: Python implementation for:

• Python-based backend services
• Command-line tools
• Integration scripts
• Testing frameworks

Both libraries implement the same SKRAP protocol for communicating with KERIA-agents.

Alternative Agent Implementations

While KERIA is the primary cloud agent implementation, the KERI ecosystem includes:

KLI (KERI Command Line Interface): Command-line tool from KERIpy that can manage AIDs locally without a cloud agent. Used for:

• Development and testing
• Organizational roles requiring direct key control
• Witness operation
• Local keystore management

Witness Agents: Specialized agents that provide witness services, implemented in KERIpy using kli witness demo for testing or production witness configurations.

Browser Extension Integration

The Signify Browser Extension (also called Polaris) provides:

• Browser-based UI for KERIA-agent interaction
• Credential presentation for web authentication
• Signing association management
• Integration with web applications using KRAM authentication

The extension communicates with KERIA-agents through the Admin Interface, enabling users to control their cloud-hosted identities from their browser.

vLEI Ecosystem Integration

KERIA-agents are fundamental to the vLEI (verifiable Legal Entity Identifier) ecosystem:

Sally: Verification service that validates credentials presented by KERIA-agents, used in regulatory reporting scenarios.

vLEI-server: Schema server providing ACDC schemas and sample credentials, integrated with KERIA-agents for credential issuance.

QVI Software: Qualified vLEI Issuer implementations that use KERIA-agents for managing QVI credentials and issuing Legal Entity credentials.

Implementation Notes

Security Considerations

Private Key Isolation: The fundamental security guarantee of KERIA-agents is that private keys never exist unencrypted on the server. The agent stores:

• Encrypted private keys: Encrypted with keys derived from the client's bran
• Encrypted salts: Used for key derivation, also encrypted
• Public keys: Stored in plaintext for verification
• Next key digests: Pre-rotated key commitments

The agent never has access to the decryption keys, which are derived from the client's passcode and never transmitted to the server.

Cooperative Delegation Security: The cooperative delegation model ensures:

• Agent cannot rotate keys without client participation
• Client retains ultimate control authority
• Agent compromise does not enable identifier theft
• Client can "fire" agent by rotating to new keys

Witness Threshold Security: KERIA-agents rely on witness consensus for duplicity detection. The TOAD (Threshold of Accountable Duplicity) parameter determines how many witnesses must confirm events, providing Byzantine fault tolerance.

Performance Characteristics

LMDB Storage: KERIA-agents use LMDB for persistent storage, providing:

• Memory-mapped file access for fast reads
• ACID transaction guarantees
• Concurrent read access
• Single-writer architecture

Asynchronous Operations: Most KERIA operations are asynchronous, requiring clients to:

1. Initiate operation (returns operation ID)
2. Poll for completion using client.operations().wait(op)
3. Clean up operation records with client.operations().delete(op)

This pattern accommodates network latency for witness communication and multi-signature coordination.

Notification Streaming: KERIA-agents use server-sent events for real-time notifications, enabling:

• Immediate credential presentation alerts
• Multi-signature coordination updates
• Key state change notifications
• Low-latency event delivery to connected clients

Multi-Tenancy Patterns

Agent Isolation: Each KERIA-agent maintains:

• Separate LMDB database files
• Independent witness configurations
• Isolated credential storage
• Per-agent authorization contexts

Resource Sharing: Multiple agents share:

• Network interfaces (same ports)
• KERIA server process
• Common witness connections
• Shared infrastructure services

Scaling Considerations: KERIA's multi-tenant architecture enables:

• Horizontal scaling by running multiple KERIA instances
• Load balancing across agent pools
• Geographic distribution for latency optimization
• Separation of high-security vs. convenience agents

Testing and Development

Local Development: For testing, developers can:

• Run KERIA locally without Docker
• Use kli witness demo for witness network
• Configure test witness OOBIs in KERIA config
• Use hardcoded brans for reproducible testing

Integration Testing: The reg-pilot repository demonstrates:

• Multi-agent coordination
• Credential issuance workflows
• Load testing with hundreds of agents
• Docker Compose orchestration

Load Testing: Document 3 shows load testing patterns:

• Parallel agent creation
• Batch credential operations
• Performance measurement
• Resource utilization monitoring

Production Deployment

Security Hardening:

• Disable Boot Interface in static worker mode
• Restrict Admin Interface to authenticated networks
• Use TLS for all interfaces
• Implement rate limiting
• Monitor for duplicity events

High Availability:

• Deploy multiple KERIA instances
• Use load balancers for Admin Interface
• Replicate witness infrastructure
• Implement backup and recovery procedures
• Monitor witness availability

Operational Monitoring:

• Track agent creation rates
• Monitor KEL growth
• Alert on witness failures
• Measure operation latency
• Log security events

Future Developments

Binary CESR Support: Current KERIA-agents use CESR base64 text encoding. Future versions may support binary CESR for:

• Reduced bandwidth
• Faster parsing
• More compact storage

Enhanced Watcher Integration: Future KERIA versions may integrate watcher networks for:

• Enhanced duplicity detection
• Distributed verification
• Increased security guarantees

Advanced Multi-Signature: Ongoing development includes:

• Improved multi-sig coordination
• Nested delegation trees
• Threshold structure optimization
• Performance improvements for large groups

Production Deployment Considerations

Security Hardening:

• Disable Boot Interface in static worker mode
• Restrict Admin Interface to authenticated networks
• Use TLS for all interfaces
• Implement rate limiting
• Monitor for duplicity events

High Availability:

• Deploy multiple KERIA instances behind load balancers
• Replicate witness infrastructure
• Implement backup and recovery for LMDB databases
• Monitor witness availability and latency

Performance Optimization:

• Use binary CESR when available (future)
• Optimize witness pool selection for latency
• Implement caching for frequently accessed key states
• Monitor operation queue depths

Testing Patterns

For development and testing:

• Use kli witness demo for local witness network
• Configure test witness OOBIs in KERIA config
• Use hardcoded brans for reproducible testing
• Docker Compose for integration testing
• Load testing with parallel agent creation

Integration with vLEI Ecosystem

KERIA-agents are fundamental to vLEI workflows:

• QVI agents issue Legal Entity credentials
• Legal Entity agents receive and present credentials
• Sally verification service validates presentations
• vLEI-server provides schema resolution
• Browser extension enables web authentication