OOBI is employed in several critical scenarios:

• Initial AID Discovery: When a validator first encounters an AID and needs to locate its KEL
• Witness Discovery: Finding witness endpoints for an identifier
• Watcher Network Bootstrap: Connecting to watcher infrastructure for duplicity detection
• Credential Schema Resolution: Locating ACDC schemas via SAIDs
• Agent Communication: Establishing connections between KERIA agents and Signify clients

Key Participants

The OOBI process involves:

1. Discloser: Entity sharing the OOBI (may be the AID controller, a witness, or any party with knowledge)
2. Discoverer: Entity receiving and resolving the OOBI
3. Service Endpoint: The URL-accessible resource providing KERI data
4. Witnesses/Watchers: Infrastructure components discovered through OOBIs

Process Flow

Basic OOBI Structure

The simplest OOBI is a tuple associating a URL with an identifier:

(url, aid)

Concrete example:

("http://8.8.5.6:8080/oobi", "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM")

OOBI URL (iurl) Format

OOBIs can be expressed as self-describing URLs where the AID is embedded in the path:

http://8.8.5.6:8080/oobi/EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM

With optional query parameters for role hints:

http://8.8.5.6:8080/oobi/EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM?role=witness&name=wan

Resolution Sequence

Step 1: OOBI Reception

• Discoverer receives OOBI through out-of-band channel (QR code, email, chat, web page)
• OOBI may be in tuple form, URL form, or structured message format

Step 2: URL Access

• Discoverer performs HTTP GET request to the OOBI URL
• Service endpoint returns KERI data (typically KEL events, witness information, or schema data)
• Response format is CESR-encoded KERI messages

Step 3: Cryptographic Verification

• Discoverer validates returned data using KERI verification protocols
• For KELs: Verify inception event, validate pre-rotation commitments, check witness receipts
• For credentials: Verify SAID integrity, validate issuer signatures
• Critical: The OOBI itself is NOT trusted—only cryptographically verified data is accepted

Step 4: State Establishment

• Discoverer updates local key state based on verified KEL
• Establishes connection to discovered witnesses/watchers
• Stores endpoint information for future interactions

State Changes

OOBI resolution triggers several state transitions:

1. Unknown → Discovered: AID moves from unknown to having known service endpoints
2. Unverified → Verified: KEL data transitions from unverified to cryptographically validated
3. Disconnected → Connected: Witness/watcher connections established
4. Incomplete → Complete: Key state becomes fully established with witness receipts

Decision Points

Role-Based Routing: If OOBI includes role parameter, discoverer routes to appropriate handler:

• role=witness: Process as witness discovery
• role=watcher: Process as watcher discovery
• role=controller: Process as direct controller endpoint

Forwarding Logic: If OOBI points to a forwarding service, the service may:

• Return the actual KEL data directly
• Provide additional OOBIs pointing to authoritative sources
• Redirect to witness endpoints

Verification Failure Handling: If cryptographic verification fails:

• Reject the discovered data
• Do NOT update key state
• Optionally attempt alternative OOBIs if available

Technical Requirements

Cryptographic Requirements

Self-Certifying Identifiers: All AIDs discovered via OOBI must be self-certifying, meaning:

• The identifier is cryptographically derived from the public key
• Verification requires no external trust authority
• Inception events establish the binding between identifier and initial keys

Pre-Rotation Security: For transferable identifiers:

• Next key commitments must be verified in each establishment event
• Pre-rotation provides post-quantum security through forward commitment

Witness Receipts: For indirect mode identifiers:

• Minimum threshold of witness receipts required (specified by TOAD)
• Receipts must be cryptographically valid signatures from designated witnesses
• KAACE algorithm ensures witness agreement

Timing Considerations

Asynchronous Resolution: OOBI resolution is inherently asynchronous:

• No guaranteed response time from service endpoints
• Witness receipt collection may require multiple round-trips
• Escrow mechanisms handle out-of-order event arrival

Caching and Staleness: Discovered information may become stale:

• KELs may have new events after OOBI resolution
• Witness endpoints may change
• Periodic re-resolution or watcher monitoring recommended

Bootstrap Timeout: Implementations should implement timeouts:

• HTTP request timeouts for unresponsive endpoints
• Overall resolution timeout for complete key state establishment
• Fallback to alternative OOBIs if primary fails

Error Handling

Network Failures:

• HTTP connection failures: Try alternative OOBIs if available
• Timeout: Implement exponential backoff for retries
• DNS resolution failures: Fall back to IP-based OOBIs

Cryptographic Verification Failures:

• Invalid signatures: Reject data, do not update state
• Broken hash chains: Treat as duplicity, report to watchers
• Insufficient witness receipts: Escrow events until threshold met

Malformed Data:

• Invalid CESR encoding: Reject and log error
• Schema validation failures: Reject credential/schema data
• Missing required fields: Treat as protocol violation

Usage Patterns

Typical Scenarios

Scenario 1: Initial AID Discovery

A verifier receives a credential presentation containing an issuer AID they've never encountered:

1. Extract issuer AID from credential
2. Obtain OOBI for issuer (may be embedded in credential metadata)
3. Resolve OOBI to get issuer's KEL
4. Verify issuer's current key state
5. Validate credential signature against issuer's keys

Scenario 2: Witness Network Bootstrap

A new controller creates an AID and needs to connect to witnesses:

1. Generate witness OOBIs from witness AID and known endpoints
2. Resolve each witness OOBI to verify witness identity
3. Send inception event to witnesses for receipting
4. Collect witness receipts to complete inception

Scenario 3: Watcher Network Discovery

A validator wants to monitor an AID for duplicity:

1. Obtain watcher network OOBI (may be well-known or published)
2. Resolve OOBI to discover watcher endpoints
3. Subscribe to watcher for AID monitoring
4. Receive notifications of any duplicitous events

Scenario 4: Schema Resolution

An ACDC processor encounters a schema SAID it hasn't cached:

1. Extract schema SAID from credential
2. Resolve schema OOBI (may be in credential metadata or well-known location)
3. Retrieve schema JSON
4. Verify schema SAID matches retrieved content
5. Cache schema for future use

Best Practices

OOBI Distribution:

• Use multiple channels for redundancy (QR code + URL + embedded in credentials)
• Include role hints to optimize resolution
• Provide multiple witness OOBIs for high availability
• Use well-known URIs (.well-known/keri/oobi/) for discoverability

Security Considerations:

• Never trust OOBI source—always verify cryptographically
• Implement BADA (Best Available Data Acceptance) policy
• Monitor for duplicity through watchers
• Use blind OOBIs when privacy required

Performance Optimization:

• Cache resolved KELs and key states
• Implement connection pooling for witness/watcher connections
• Use percolated discovery to share OOBIs within trust networks
• Batch OOBI resolutions when processing multiple credentials

Error Recovery:

• Implement retry logic with exponential backoff
• Maintain multiple OOBI sources for critical identifiers
• Use escrow for out-of-order events
• Log resolution failures for debugging

Integration Considerations

With KERIA/Signify:

• KERIA agents expose OOBI endpoints for client discovery
• Signify clients use OOBIs to bootstrap agent connections
• Agent-client authentication uses challenge-response after OOBI resolution

With ACDC Credentials:

• Credentials may embed issuer OOBIs in metadata
• Schema OOBIs enable schema resolution
• IPEX protocol uses OOBIs for presentation exchange

With Witness/Watcher Networks:

• Witnesses publish OOBIs for discoverability
• Watchers use OOBIs to monitor multiple identifiers
• Promiscuous mode watchers accept any OOBI

With DID Methods:

• did:keri embeds OOBI in DID document
• did:webs uses web infrastructure for OOBI hosting
• DID resolution may trigger OOBI resolution for key state updates

OOBI Variants

Verbose OOBI

Structured JSON format with complete metadata:

{
  "eid": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
  "scheme": "http",
  "url": "http://8.8.5.6:8080/",
  "role": "witness",
  "name": "wan"
}

Multi-OOBI (MOOBI)

Bundles multiple OOBIs for a single identifier:

• Provides redundancy through multiple endpoints
• Enables load balancing across witnesses
• Challenges: Authorization complexity for each endpoint

Blind OOBI (BOOBI)

OOBI where witness information is not embedded:

• Verification relies on external mechanisms
• Used when witness list is known through other channels
• Provides privacy by not exposing witness relationships

Self OOBI (SOOBI)

Identifier introduces itself:

• Controller publishes own OOBI
• Enables self-service discovery
• Common pattern for public identifiers

Security Model

Trust Boundaries

Untrusted Components:

• The OOBI itself (may come from adversary)
• The URL/endpoint (may be compromised)
• Network infrastructure (DNS, routing)
• Any intermediaries in discovery path

Trusted Components:

• Cryptographic verification algorithms
• Local key state validation logic
• Witness threshold policies
• Pre-rotation commitments in KEL

Attack Resistance

OOBI Spoofing: Attacker provides false OOBI

• Mitigation: Cryptographic verification rejects invalid KELs
• Result: No state change, attack fails

Man-in-the-Middle: Attacker intercepts OOBI resolution

• Mitigation: KEL signatures and hash chains detect tampering
• Result: Verification fails, attack detected

Replay Attacks: Attacker replays old KEL data

• Mitigation: Sequence numbers and monotonic updates prevent rollback
• Result: Stale data rejected

Duplicity Attacks: Attacker provides conflicting KELs

• Mitigation: Duplicity detection through witnesses/watchers
• Result: Conflict detected, reported, identifier reputation damaged

Standardization

OOBI is formalized in IETF draft-ssmith-oobi, establishing it as a standardized component of the KERI protocol suite. The specification defines:

• OOBI URL syntax and semantics
• Resolution protocol requirements
• Security considerations
• Interoperability requirements

This standardization ensures consistent implementation across KERI ecosystem tools including KERIpy, KERIA, Signify, and other KERI implementations.

Verification Failures:

if not verify_kel_signatures(kel_data):
    logger.error(f"Signature verification failed for AID {aid}")
    # Do NOT update key state
    raise VerificationError("Invalid KEL signatures")

Integration Patterns

With KERIA Agents:

• KERIA exposes OOBIs at /oobi/{aid} endpoints
• Clients resolve agent OOBI during bootstrap
• Agent-client authentication follows OOBI resolution

With Credential Processing:

• Extract issuer OOBI from credential metadata
• Resolve issuer KEL before signature verification
• Cache issuer key state for batch processing

With Witness Networks:

• Generate witness OOBIs from AID and known endpoints
• Resolve all witness OOBIs during inception
• Maintain persistent connections to witnesses

Testing Considerations

Unit Tests:

• Test OOBI parsing for all formats (tuple, URL, JSON)
• Test cryptographic verification with valid/invalid data
• Test error handling for network failures
• Test state update logic with various KEL scenarios

Integration Tests:

• Test complete resolution pipeline with real witnesses
• Test OOBI resolution with multiple concurrent requests
• Test failover to alternative OOBIs
• Test percolated discovery scenarios

Security Tests:

• Test with malicious OOBIs (invalid URLs, malformed data)
• Test replay attack resistance
• Test duplicity detection through watchers
• Test MITM attack resistance through cryptographic verification