Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 54 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.
A numerical label (IPv4 or IPv6) assigned to devices on a network using Internet Protocol, serving to identify network interfaces and provide location addressing for routing. In KERI, IP addresses are used for service endpoints (witnesses, watchers) but are not trusted as part of the cryptographic root-of-trust.
An IP address (Internet Protocol address) is a numerical label assigned to each device connected to a computer network that uses the Internet Protocol for communication. The canonical definition from the KERI/GLEIF glossary identifies two principal functions:
IP addresses exist in two versions:
192.0.2.1, 8.8.5.6, 127.0.0.1)In traditional Internet architecture, IP addresses serve as the foundational addressing mechanism for host-to-host communication, enabling devices to send and receive data packets across networks.
KERI's architecture implements a fundamental separation between discovery and authentication layers:
This separation is architecturally critical. As the KERI specification states, KERI provides a cryptographic root-of-trust that is completely . IP addresses are treated purely as a discovery and communication mechanism—they are .
KERI implementations must never rely on IP addresses for authentication. IP addresses are used only for:
Implementations should clearly separate:
The IP layer is treated as an availability problem, not a security problem.
While domain names (which resolve to IP addresses) may be used in OOBIs for convenience, KERI's security does not depend on DNS integrity. Implementations should support:
The OOBI (Out-Of-Band Introduction) specification explicitly addresses this: "IP infrastructure is not trusted by KERI. An OOBI by itself is considered insecure and serves only to jump-start discovery, not to establish trust." This design philosophy allows KERI to leverage existing IP infrastructure for convenience while maintaining security through end-verifiable cryptographic proofs.
IP addresses enable the location of KERI infrastructure components:
Witness Endpoints: IP addresses (often with port numbers) where witnesses can be reached to provide key event receipts. Network traces from KERIpy demonstrations show witness communication at addresses like 127.0.0.1:5621 and 127.0.0.1:52117 for local testing, or public IPs for production deployments.
Watcher Endpoints: Network locations where validators monitoring key event logs operate. Watchers run in "promiscuous mode" using the same code as witnesses but without being designated by controllers.
Controller Endpoints: Where AID controllers expose their services, including KERIA cloud agents that provide HTTP endpoints for command and control operations.
Registrar and Backer Endpoints: For transaction event log (TEL) infrastructure supporting verifiable credential registries.
Out-of-Band Introduction (OOBI) URLs combine IP addresses (or domain names) with AIDs for bootstrap discovery. The basic structure:
http://8.8.5.6:8080/oobi/EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM
This URL contains:
The IP address provides the network location, but the OOBI itself is not cryptographically trusted. All authentication occurs through KERI's BADA (Best Available Data Acceptance) mechanisms after initial discovery. As the specification emphasizes, "discovery via URI, trust via KERI."
OOBI can reference:
Keridemlia provides a distributed hash table (DHT) mapping between AIDs and witness IP addresses, offering DNS-like functionality specifically for KERI without relying on traditional DNS infrastructure. The glossary defines Keridemlia as performing:
This three-level resolution system enables decentralized discovery of witness network locations. The DHT architecture (based on Kademlia) provides:
Keridemlia addresses the "vacuous discovery" problem—how to find IP resources for completely decentralized AIDs that have no inherent connection to internet addressing.
The GAR documentation provides extensive detail on IP address usage in vLEI credential issuance infrastructure. GARs must:
Configure Docker networking: The GAR software runs in Docker containers that expose KERI services on specific IP addresses and ports. The documentation references localhost (127.0.0.1) for development and testing.
Establish network connectivity: To GLEIF witness network and other participants. The documentation specifies that all participants "Maintain network connectivity to GLEIF witness network and other participants."
Conduct identity assurance over video: NIST-800-63-3 IAL-2 compliance requires live video sessions between GARs, which inherently depend on IP connectivity for video calling infrastructure.
QVI setup documentation details similar IP addressing requirements:
Group multisig coordination: Creating QVI group multisig AIDs requires real-time coordination between multiple participants over IP networks. The process includes:
Witness pool configuration: QVIs must configure witness pools with specific IP addresses where witnesses can be reached for key event witnessing services.
Delegated identifier creation: QVI AIDs are delegated from GLEIF External AID or GLEIF Internal AID, requiring network communication with GLEIF infrastructure at specific IP endpoints.
Localhost/127.0.0.1 for testing: KERIpy demonstrations and development environments extensively use 127.0.0.1 (localhost) for testing. Network traces show:
127.0.0.1:5621 for local witness testing127.0.0.1:52117 for peer-to-peer event exchangePublic IPs for production witnesses: Production deployments require publicly accessible IP addresses where witnesses expose TCP endpoints for:
Well-known witnesses: The documentation references "well-known witnesses" created with predictable identifiers for testing purposes, which have associated test IP addresses.
The KERIpy demo vectors provide raw network traces showing IP-level communication:
Event exchange at 127.0.0.1:5621:
Tx (Transmit) and Rx (Receive) messages
Inception events (icp) establishing AIDs
Rotation events (rot) changing key state
Interaction events (ixn) anchoring data
Validation receipts (vrc) from witnesses
Event exchange at 127.0.0.1:52117: Similar bidirectional communication showing complete KEL construction through peer-to-peer message exchange over TCP.
These traces demonstrate that while KERI messages are cryptographically self-verifying (CESR-encoded with signatures), they are transmitted over traditional TCP/IP networking infrastructure.
The glossary defines TCP endpoint as a service endpoint using the Transmission Control Protocol with IP addresses. KERI infrastructure heavily relies on TCP for:
Reliable message delivery: TCP provides ordered, error-checked delivery of KERI event streams
Connection-oriented communication: Between controllers, witnesses, and watchers
Streaming protocols: CESR streams transmitted over TCP connections
The specification notes that KERI can operate over TCP, UDP, or HTTP, but TCP is most common for witness/watcher infrastructure.
KERIA (KERI Agent in the cloud) exposes three separate HTTP endpoints on three separate network interfaces:
Each interface has distinct IP address/port configurations, enabling:
The SKWA (Simple KERI for Web Auth) and SKRAP (Signify KERIA Request Authentication Protocol) specifications detail how clients connect to KERIA agents via HTTP endpoints at specific IP addresses, with KRAM (KERI Request Authentication Method) providing replay attack protection.
KERI's security model explicitly accounts for IP-layer vulnerabilities:
DNS hijacking: Attackers compromise DNS to redirect traffic to malicious IPs. KERI defends by treating DNS resolution as untrusted—even if DNS is compromised, cryptographic verification fails for invalid KELs.
BGP hijacking: Border Gateway Protocol attacks can redirect IP traffic. KERI's end-to-end verification means even if traffic is intercepted and modified, signature verification will fail.
Man-in-the-middle: Attackers intercept IP traffic to read or modify messages. KERI messages are:
IP spoofing: Attackers forge source IP addresses. KERI doesn't trust source IPs for authentication—only cryptographic signatures matter.
The SPAC (Secure Privacy, Authenticity, and Confidentiality) protocol specification addresses confidentiality at the message level, independent of IP-layer encryption. This "defense in depth" approach means KERI security doesn't depend on TLS/SSL or other IP-layer security mechanisms, though they provide additional protection.
IP addresses present privacy challenges that KERI explicitly addresses:
IP-based correlation: Observers can correlate activities by IP address even when using different AIDs. The SPAC protocol and sustainable privacy framework address this through:
Metadata leakage: IP addresses are "non-content metadata" that can reveal:
The PAC theorem (Privacy, Authenticity, Confidentiality trilemma) recognizes that achieving all three properties simultaneously at the highest level is impossible. KERI prioritizes:
IP address anonymization: While not directly part of KERI protocol, implementations can use:
KERI's security properties remain intact regardless of these transport-layer anonymization techniques.
The glossary defines host as the part of a URL identifying the server location, which can be:
example.com)192.168.1.1)KERI treats both as equivalent for discovery purposes—both are untrusted bootstrapping mechanisms. The choice between domain names and IP addresses involves trade-offs:
Domain names:
IP addresses:
Multiple sources discuss Docker containerization for KERI infrastructure:
Container IP allocation: Docker assigns IP addresses to containers:
172.17.0.2)Port mapping: Container ports mapped to host IP addresses:
docker run -p 127.0.0.1:8080:8080 gleif/keri
This maps container port 8080 to host localhost:8080.
Volume mounting: The GAR documentation specifies mounting $HOME/.gar directory for persistent storage, which includes networking configuration.
Multi-container coordination: KERI deployments often involve:
Proper IP address management across containers is critical for these components to discover and communicate with each other.
Witness pools require careful IP address planning:
Geographic distribution: Witnesses should be at diverse IP addresses/networks for:
Threshold configuration: The TOAD (Threshold of Accountable Duplicity) parameter determines how many witnesses must confirm events. With N witnesses at different IPs, controllers set M >= N - F where F is the tolerated fault count.
Dynamic witness lists: Controllers can rotate witness pools, requiring:
Creating group multisig AIDs involves extensive IP-based coordination:
Six-stage GAR process:
Seven-stage QVI rotation: Similar IP-based coordination when modifying QVI group membership, with additional:
These processes demonstrate that while KERI's security doesn't depend on IP infrastructure, practical operations heavily utilize IP networking for coordination.
The vLEI ecosystem's identity assurance processes have specific IP address requirements:
Video call requirements: GLEIF's NIST-800-63-3 IAL-2 compliance mandates:
These video calls inherently require IP connectivity. The GAR documentation emphasizes that all participants must "Maintain network connectivity to GLEIF witness network and other participants."
Two-factor authentication: Often involves:
Credential issuance flows: When a QVI issues a vLEI credential:
The glossary includes anycast address as a network addressing concept where multiple servers share the same IP address. This is relevant for:
Witness redundancy: Multiple witness instances at the same anycast IP for:
Watcher services: Similar anycast patterns for:
IPv4 exhaustion: Limited 32-bit address space creates challenges:
IPv6 advantages: 128-bit addresses provide:
Dual-stack operation: KERI implementations should support both:
KERI implements zero-trust principles where IP addresses play a specific role:
Never trust, always verify: IP addresses provide:
Microsegmentation: KERIA's three-interface design enables:
Continuous verification: Every KERI message verified regardless of:
IP addresses in the KERI ecosystem occupy a carefully delineated role: essential for network discovery and communication, but explicitly excluded from the security model. This architectural decision enables KERI to leverage ubiquitous IP infrastructure while maintaining cryptographic security properties that don't depend on IP-layer trust.
Key principles:
For KERI implementers and infrastructure operators, understanding IP address roles is critical for:
The vLEI ecosystem's extensive use of IP-based infrastructure for GAR setup, QVI operations, and credential issuance demonstrates that while KERI's security doesn't depend on IPs, real-world operations utilize them extensively. This pragmatic approach—leveraging existing infrastructure while building cryptographic security on top—exemplifies KERI's philosophy of "minimally sufficient means" for creating a trust spanning layer for the internet.