Formal Specification References

IPEX is defined in the IETF Internet Draft specification:

• Primary Specification: draft-ssmith-ipex (IETF Internet Draft)
• Status: Informational category, work in progress
• Dependencies:
  • ACDC-ID (Authentic Chained Data Container specification)
  • KERI-ID (Key Event Receipt Infrastructure)
  • SAID-ID (Self-Addressing Identifier)
  • CESR-ID (Composable Event Streaming Representation)
  • OOBI-ID (Out-Of-Band Introduction)
  • PTEL-ID (Public Transaction Event Log)
  • Proof-ID (CESR Proof Signatures)
  • DIDK-ID (DID KERI method)

Version History and Evolution

IPEX emerged from practical implementation experience in the vLEI (verifiable Legal Entity Identifier) ecosystem developed by GLEIF. The protocol evolved to address real-world challenges in credential exchange:

• Early Development (2022): Initial specification work began as part of vLEI implementation
• Specification Maturation (2023): IETF draft formalization with comprehensive message types
• Production Deployment (2023-2024): GLEIF vLEI ecosystem adoption in production
• Ongoing Evolution: Continued refinement based on implementation feedback

The protocol specification explicitly acknowledges sections marked as "TODO" including Introduction, Security Considerations, and Acknowledgments, indicating active development status.

Protocol Architecture

Layering and Component Organization

IPEX operates as a presentation layer protocol within the KERI protocol stack:

┌─────────────────────────────────────┐
│   Application Layer                 │
│   (vLEI, Custom Credentials)        │
├─────────────────────────────────────┤
│   IPEX Protocol Layer               │
│   (Issuance & Presentation)         │
├─────────────────────────────────────┤
│   ACDC Layer                        │
│   (Credential Structure)            │
├─────────────────────────────────────┤
│   KERI Layer                        │
│   (Identifier & Key Management)     │
├─────────────────────────────────────┤
│   CESR Layer                        │
│   (Encoding & Serialization)        │
└─────────────────────────────────────┘

Layer Responsibilities:

1. CESR Foundation: Provides composable encoding for all protocol messages
2. KERI Infrastructure: Manages AIDs (Autonomic Identifiers), KELs (Key Event Logs), and cryptographic verification
3. ACDC Structure: Defines credential format, SAIDs, and chaining mechanisms
4. IPEX Protocol: Orchestrates credential exchange workflows
5. Application Logic: Implements domain-specific credential types and business rules

Data Flow and Control Flow

IPEX implements asynchronous message-based communication with the following flow patterns:

Issuance Exchange Flow:

Issuer                           Holder
  │                                │
  │──────── /ipex/apply ──────────>│  (Holder requests credential)
  │                                │
  │<─────── /ipex/offer ───────────│  (Issuer offers credential)
  │                                │
  │──────── /ipex/agree ──────────>│  (Holder agrees to terms)
  │                                │
  │<─────── /ipex/grant ───────────│  (Issuer grants credential)
  │                                │
  │──────── /ipex/admit ──────────>│  (Holder admits receipt)
  │                                │

Presentation Exchange Flow:

Verifier                         Holder
  │                                │
  │──────── /ipex/apply ──────────>│  (Verifier requests presentation)
  │                                │
  │<─────── /ipex/offer ───────────│  (Holder offers to present)
  │                                │
  │──────── /ipex/agree ──────────>│  (Verifier agrees to terms)
  │                                │
  │<─────── /ipex/grant ───────────│  (Holder grants presentation)
  │                                │
  │──────── /ipex/admit ──────────>│  (Verifier admits receipt)
  │                                │

Key Architectural Properties:

• Bidirectional Negotiation: Both parties can initiate exchanges
• Multi-Step Workflow: Exchanges involve multiple message rounds
• Asynchronous Operation: No requirement for simultaneous online presence
• Stateful Protocol: Parties maintain exchange state across messages

State Management Approach

IPEX implements distributed state management where each party maintains:

1. Exchange State: Current status of ongoing exchanges (pending, completed, rejected)
2. Credential State: Status of issued/held credentials (active, revoked, expired)
3. Notification State: Unread messages and pending actions
4. Registry State: TEL (Transaction Event Log) status for credential lifecycle

State synchronization occurs through:

• KERI Event Logs: Authoritative state anchored in KELs
• Mailbox Services: Asynchronous message delivery for offline parties
• Witness Networks: Distributed consensus on key events
• Registry Queries: Real-time credential status verification

Message Formats & Encoding

Message Types and Structure

IPEX defines five core message types using the KERI exn (exchange) message format:

1. Apply Message (/ipex/apply)

Initiates an exchange by requesting credential issuance or presentation.

Structure:

{
  "v": "KERI10JSON00011c_",
  "t": "exn",
  "d": "<message SAID>",
  "i": "<sender AID>",
  "p": "<prior event SAID>",
  "dt": "2024-01-15T10:30:00.000000+00:00",
  "r": "/ipex/apply",
  "q": {
    "m": "<optional message text>",
    "i": "<target AID>"
  },
  "a": [
    "<attachment SAID 1>",
    "<attachment SAID 2>"
  ]
}

Field Semantics:

• v: CESR version string
• t: Message type ("exn" for exchange)
• d: Message SAID
• i: Sender's AID
• p: Prior event reference for ordering
• dt: ISO 8601 timestamp
• r: Route (IPEX message type)
• q: Query/payload section
• a: Attachment SAIDs

2. Offer Message (/ipex/offer)

Responds to an apply by offering credential issuance or presentation.

Structure:

{
  "v": "KERI10JSON00011c_",
  "t": "exn",
  "d": "<message SAID>",
  "i": "<sender AID>",
  "p": "<prior event SAID>",
  "dt": "2024-01-15T10:31:00.000000+00:00",
  "r": "/ipex/offer",
  "q": {
    "m": "<optional message text>",
    "i": "<target AID>"
  },
  "a": [
    "<credential SAID>"
  ]
}

The offer message includes the ACDC credential (or credential reference) being offered in the attachments section.

3. Agree Message (/ipex/agree)

Accepts an offer and agrees to proceed with the exchange.

Structure:

{
  "v": "KERI10JSON00011c_",
  "t": "exn",
  "d": "<message SAID>",
  "i": "<sender AID>",
  "p": "<prior event SAID>",
  "dt": "2024-01-15T10:32:00.000000+00:00",
  "r": "/ipex/agree",
  "q": {
    "m": "<optional message text>",
    "i": "<target AID>"
  }
}

4. Grant Message (/ipex/grant)

Grants the credential or presentation, completing the exchange.

Structure:

{
  "v": "KERI10JSON00011c_",
  "t": "exn",
  "d": "<message SAID>",
  "i": "<sender AID>",
  "p": "<prior event SAID>",
  "dt": "2024-01-15T10:33:00.000000+00:00",
  "r": "/ipex/grant",
  "q": {
    "m": "<optional message text>",
    "i": "<target AID>"
  },
  "a": [
    "<credential SAID>",
    "<signature attachments>"
  ]
}

The grant message includes the complete ACDC with CESR Proof signature attachments.

5. Admit Message (/ipex/admit)

Acknowledges receipt and completes the exchange.

Structure:

{
  "v": "KERI10JSON00011c_",
  "t": "exn",
  "d": "<message SAID>",
  "i": "<sender AID>",
  "p": "<prior event SAID>",
  "dt": "2024-01-15T10:34:00.000000+00:00",
  "r": "/ipex/admit",
  "q": {
    "m": "<optional message text>",
    "i": "<target AID>"
  }
}

Encoding Schemes

IPEX messages use CESR (Composable Event Streaming Representation) encoding with support for multiple serialization formats:

Supported Serializations:

• JSON: Human-readable text format (primary for examples)
• CBOR: Compact binary format for efficiency
• MGPK: MessagePack binary format

CESR Encoding Properties:

• Composability: Messages can be concatenated and parsed as streams
• Self-framing: Each primitive includes length information
• Dual encoding: Text and binary representations are interconvertible
• Qualified primitives: Cryptographic material includes derivation codes

Attachment Encoding:

IPEX messages include CESR attachments for:

• Signatures: CESR Proof format signatures
• Credentials: Complete ACDC structures
• Receipts: Witness receipts for events

Attachments are appended to the message body using CESR count codes and group codes for efficient parsing.

Field Definitions and Semantics

Standard KERI Exchange Message Fields:

• v (Version String): Identifies CESR version and serialization format

  • Format: KERI<major><minor><serialization><size>_
  • Example: KERI10JSON00011c_

• t (Message Type): Always "exn" for IPEX messages

• d (Digest/SAID): Self-addressing identifier of the message

  • Computed over the entire message structure
  • Provides tamper-evident integrity

• i (Identifier): Sender's AID

  • Must be a valid KERI identifier
  • Used for signature verification

• p (Prior): SAID of prior event in sender's KEL

  • Establishes event ordering
  • Prevents replay attacks

• dt (DateTime): ISO 8601 timestamp

  • Used for KRAM (KERI Request Authentication Method)
  • Provides replay attack protection

• r (Route): IPEX message type identifier

  • Format: /ipex/<message-type>
  • Determines message handling logic

• q (Query/Payload): Message-specific payload

  • Contains exchange-specific data
  • Structure varies by message type

• a (Attachments): Array of attachment SAIDs

  • References CESR attachments
  • Includes credentials, signatures, receipts

Protocol Mechanics

Message Exchange Patterns

IPEX implements negotiated exchange patterns with multiple interaction models:

Solicited Issuance Pattern

Scenario: Holder requests credential from Issuer

1. Holder → Issuer: /ipex/apply (credential request)
2. Issuer → Holder: /ipex/offer (credential offer with terms)
3. Holder → Issuer: /ipex/agree (acceptance of terms)
4. Issuer → Holder: /ipex/grant (credential issuance)
5. Holder → Issuer: /ipex/admit (receipt acknowledgment)

Key Properties:

• Holder initiates the exchange
• Issuer can include terms and conditions in offer
• Multi-step negotiation allows for contractual agreements
• Final admit provides non-repudiable receipt

Unsolicited Issuance Pattern

Scenario: Issuer proactively issues credential to Holder

1. Issuer → Holder: /ipex/offer (unsolicited credential offer)
2. Holder → Issuer: /ipex/agree (acceptance)
3. Issuer → Holder: /ipex/grant (credential issuance)
4. Holder → Issuer: /ipex/admit (receipt acknowledgment)

Key Properties:

• Issuer initiates without prior request
• Holder can reject by not responding with agree
• Useful for pre-authorized credentials

Presentation Request Pattern

Scenario: Verifier requests credential presentation from Holder

1. Verifier → Holder: /ipex/apply (presentation request)
2. Holder → Verifier: /ipex/offer (presentation offer)
3. Verifier → Holder: /ipex/agree (acceptance)
4. Holder → Verifier: /ipex/grant (credential presentation)
5. Verifier → Holder: /ipex/admit (verification acknowledgment)

Key Properties:

• Verifier specifies required credential types
• Holder controls what is disclosed (graduated disclosure)
• Verifier can specify acceptable issuers
• Supports selective disclosure and partial disclosure

Proactive Presentation Pattern

Scenario: Holder proactively presents credential to Verifier

1. Holder → Verifier: /ipex/offer (unsolicited presentation)
2. Verifier → Holder: /ipex/agree (acceptance)
3. Holder → Verifier: /ipex/grant (credential presentation)
4. Verifier → Holder: /ipex/admit (verification acknowledgment)

Key Properties:

• Holder initiates without request
• Useful for access control scenarios
• Verifier can reject by not responding

State Transitions

IPEX exchanges follow a finite state machine model:

┌─────────┐
│  IDLE   │
└────┬────┘
     │
     │ apply/offer
     ▼
┌─────────┐
│ PENDING │
└────┬────┘
     │
     │ agree
     ▼
┌─────────┐
│ AGREED  │
└────┬────┘
     │
     │ grant
     ▼
┌─────────┐
│ GRANTED │
└────┬────┘
     │
     │ admit
     ▼
┌─────────┐
│COMPLETED│
└─────────┘

State Definitions:

• IDLE: No active exchange
• PENDING: Exchange initiated, awaiting response
• AGREED: Terms accepted, awaiting credential/presentation
• GRANTED: Credential/presentation delivered, awaiting acknowledgment
• COMPLETED: Exchange successfully completed

Error States:

• REJECTED: Exchange explicitly rejected by recipient
• TIMEOUT: Exchange expired due to inactivity
• INVALID: Exchange failed validation checks

Timing and Ordering Requirements

Replay Attack Protection:

IPEX implements KRAM (KERI Request Authentication Method) for replay protection:

• Timestamp Windows: Messages must have timestamps within acceptable drift
• Prior Event References: p field establishes causal ordering
• Nonce Requirements: Each message has unique SAID

Message Ordering:

• Causal Ordering: Messages reference prior events via p field
• Timestamp Ordering: dt field provides temporal ordering
• KEL Anchoring: Critical events anchored in KEL for ordering

Timeout Handling:

• Exchange Timeouts: Implementations should timeout inactive exchanges
• Credential Expiry: ACDCs may include expiration dates
• Registry Checks: Real-time TEL queries for revocation status

Security Properties

Threat Model

IPEX operates under the KERI threat model with specific considerations for credential exchange:

Adversary Capabilities:

1. Network Adversary: Can observe, delay, or drop messages
2. Compromised Parties: May attempt to forge credentials or presentations
3. Replay Attackers: May attempt to reuse valid messages
4. Correlation Attackers: May attempt to link credential presentations

Trust Assumptions:

• Cryptographic Primitives: Assumes computational hardness of cryptographic functions
• Key Management: Assumes parties protect their private keys
• Witness Honesty: Assumes sufficient honest witnesses in pools
• Registry Integrity: Assumes TEL registries are maintained correctly

Security Guarantees

Authenticity:

• Message Authenticity: All messages signed by sender's AID
• Credential Authenticity: ACDCs signed by issuer's AID
• Non-Repudiation: Signatures provide non-repudiable proof of authorship
• Integrity: SAIDs ensure tamper-evident messages and credentials

Confidentiality:

• Transport Security: Messages should be transmitted over secure channels
• Selective Disclosure: Graduated disclosure minimizes information exposure
• Private ACDCs: UUID fields enable privacy-preserving credentials
• Contractual Protection: Chain-link confidentiality provides legal protections

Availability:

• Asynchronous Operation: No requirement for simultaneous online presence
• Mailbox Services: Store-and-forward for offline parties
• Witness Networks: Distributed availability through witness pools

Privacy:

• Minimal Disclosure: Only required information disclosed
• Unlinkability: Different presentations use different AIDs when desired
• Selective Disclosure: Attribute-level disclosure control
• Compact Variants: SAID references instead of full data

Attack Resistance

Replay Attack Resistance:

• KRAM Protection: Timestamp-based replay prevention
• Prior Event References: Causal ordering prevents reuse
• Unique SAIDs: Each message has unique identifier

Forgery Resistance:

• Digital Signatures: All messages and credentials signed
• Key Event Logs: KEL provides authoritative key state
• Witness Receipts: Distributed consensus on events

Correlation Resistance:

• Pairwise AIDs: Different identifiers for different relationships
• Selective Disclosure: Minimal information exposure
• Private Credentials: UUID-based privacy protection

Revocation Resistance:

• Real-Time Checks: TEL queries for current status
• Grace Periods: Configurable revocation timing
• Registry Anchoring: Revocation events anchored in KEL

Interoperability

Dependencies on KERI/ACDC Protocols

IPEX is deeply integrated with the KERI protocol suite:

KERI Infrastructure:

• AIDs: All parties identified by Autonomic Identifiers
• KELs: Key state verified through Key Event Logs
• Witnesses: Event receipting and consensus
• Watchers: Duplicity detection and monitoring

ACDC Credentials:

• ACDC Structure: Credentials follow ACDC specification
• SAIDs: Self-addressing identifiers for integrity
• Edges: Credential chaining through edge properties
• Rules: Ricardian contracts for terms and conditions

CESR Encoding:

• CESR: All messages use CESR encoding
• CESR Proof: Signature attachments
• Primitives: Cryptographic material as CESR primitives

Supporting Protocols:

• OOBI: Discovery of endpoints and key state
• TEL: Credential lifecycle management
• KRAM: Request authentication

Integration Points

Application Layer Integration:

• vLEI Ecosystem: GLEIF's verifiable LEI implementation
• Custom Credentials: Domain-specific ACDC types
• Business Logic: Application-specific validation rules

Transport Layer Integration:

• HTTP/HTTPS: RESTful API endpoints
• WebSockets: Real-time message delivery
• Mailbox Services: Asynchronous message queuing

Storage Layer Integration:

• KEL Storage: Persistent key event logs
• Credential Storage: ACDC credential databases
• Registry Storage: TEL transaction logs

Identity Layer Integration:

• DID Methods: did:keri and did:webs integration
• Verifiable Credentials: W3C VC compatibility layer
• Presentation Exchange: DIF Presentation Exchange alignment

Implementation Considerations

Common Challenges

Asynchronous State Management:

• Challenge: Tracking multiple concurrent exchanges across parties
• Consideration: Implement robust state machines with timeout handling
• Best Practice: Use exchange SAIDs as correlation identifiers

Credential Lifecycle Tracking:

• Challenge: Maintaining current status of issued/held credentials
• Consideration: Implement TEL monitoring for revocation
• Best Practice: Cache credential status with periodic refresh

Privacy-Preserving Disclosure:

• Challenge: Balancing disclosure requirements with privacy
• Consideration: Implement graduated disclosure strategies
• Best Practice: Default to minimal disclosure, expand as needed

Multi-Party Coordination:

• Challenge: Coordinating exchanges involving multiple parties
• Consideration: Handle multi-sig scenarios for group identifiers
• Best Practice: Implement escrow mechanisms for partial signatures

Performance Considerations

Message Size Optimization:

• Use compact variants of ACDCs when possible
• Leverage SAID references instead of full credential inclusion
• Implement CBOR or MGPK serialization for binary efficiency

Network Efficiency:

• Batch multiple exchanges when possible
• Implement message compression for large credentials
• Use OOBI caching to reduce discovery overhead

Cryptographic Performance:

• Cache KEL verification results
• Implement signature verification batching
• Use hardware acceleration for cryptographic operations

Scalability Patterns:

• Implement horizontal scaling for mailbox services
• Use distributed witness pools for load distribution
• Implement credential caching strategies

Security Implementation Guidance

Key Management:

• Protect private keys using HSMs or secure enclaves
• Implement key rotation procedures
• Use pre-rotation for quantum resistance

Transport Security:

• Always use TLS for message transport
• Implement certificate pinning for critical endpoints
• Use mutual TLS for high-security scenarios

Validation Requirements:

• Verify all signatures on received messages
• Check KEL consistency and witness receipts
• Validate ACDC schema compliance
• Query TEL for credential status

Privacy Protection:

• Implement selective disclosure by default
• Use pairwise AIDs for different relationships
• Apply chain-link confidentiality contracts
• Minimize credential correlation opportunities

Testing Strategies

Unit Testing:

• Test message serialization/deserialization
• Verify state machine transitions
• Validate cryptographic operations

Integration Testing:

• Test multi-party exchange workflows
• Verify KEL and TEL integration
• Test OOBI resolution

Security Testing:

• Replay attack testing
• Signature forgery attempts
• Timing attack analysis
• Privacy leakage assessment

Interoperability Testing:

• Cross-implementation compatibility
• Different serialization format support
• Multi-vendor credential exchange

Privacy Implementation

Graduated Disclosure: Implement support for compact, partial, selective, and full disclosure variants. Default to most compact disclosure appropriate for the use case.

Pairwise AIDs: For privacy-sensitive applications, use different AIDs for different relationships to prevent correlation across contexts.

Contractual Protection: When implementing chain-link confidentiality, include Ricardian contracts in the rules section of ACDCs and require explicit agreement before disclosure.

Multi-Signature Coordination

Group Identifiers: For multi-sig AIDs, IPEX exchanges require coordination among multiple signers. Implement escrow mechanisms to collect partial signatures before completing grant messages.

Threshold Satisfaction: Verify that grant messages include sufficient signatures to meet the signing threshold of the issuer's AID.

Rotation Handling: Monitor for rotation events that change the authoritative key set during an exchange and handle appropriately (typically by restarting the exchange with updated keys).

Error Handling

Validation Failures: When message or credential validation fails, implementations should:

• Log the failure with detailed error information
• Optionally notify the sender (may reveal information to attacker)
• Transition exchange to INVALID state
• Retain failed messages for forensic analysis

Timeout Handling: When exchanges timeout:

• Transition to TIMEOUT state
• Clean up associated resources
• Optionally notify the counterparty
• Retain exchange history for audit

Revocation Handling: When a credential is revoked during an exchange:

• Query TEL for current status
• Reject presentations of revoked credentials
• Notify the presenter of revocation status
• Log revocation for audit trail

Performance Optimization

Caching Strategies:

• Cache KEL verification results with TTL
• Cache TEL credential status with periodic refresh
• Cache OOBI resolution results
• Cache schema documents for ACDC validation

Batch Processing:

• Batch signature verifications when processing multiple messages
• Batch TEL queries for multiple credentials
• Batch witness receipt collection

Asynchronous Operations:

• Use asynchronous I/O for network operations
• Implement message queuing for high-throughput scenarios
• Use worker pools for cryptographic operations

Testing Requirements

Interoperability Testing: IPEX implementations should be tested against other implementations using standardized test vectors. The vLEI ecosystem provides reference test cases.

Security Testing: Implementations must be tested for:

• Replay attack resistance
• Signature forgery detection
• KEL inconsistency detection
• Revoked credential rejection

Privacy Testing: Verify that:

• Minimal disclosure is enforced
• Correlation opportunities are minimized
• Selective disclosure works correctly
• Private ACDCs maintain privacy properties