Key Components

Version String (v)

The version string follows KERI's regexable format: KERI10JSON00011c_

• Protocol identifier: KERI10 indicates KERI version 1.0
• Serialization type: JSON specifies JSON encoding (alternatives: CBOR, MGPK)
• Size indicator: 00011c (hexadecimal) specifies message body length
• Terminator: _ marks the end of the version string

This format enables cold-start stream parsing where processors can determine message boundaries without parsing the entire content.

Message Type (t)

The t field value "exn" distinguishes exchange messages from:

• "icp" - Inception events
• "rot" - Rotation events
• "ixn" - Interaction events
• "rct" - Receipt messages
• "qry" - Query messages
• "rpy" - Reply messages

This type system enables KERI processors to route messages to appropriate handlers.

Datetime (dt)

The datetime field uses ISO 8601 format with microsecond precision:

2023-08-15T14:30:00.000000+00:00

This timestamp serves multiple purposes:

1. Replay attack protection: Recipients can reject messages outside acceptable time windows
2. Temporal ordering: Enables chronological sequencing of exchanges
3. Audit trails: Provides verifiable timestamps for compliance

The KRAM (KERI Request Authentication Mechanism) specification defines how datetime fields interact with replay protection windows.

Route (r)

The route field uses a hierarchical namespace structure:

/protocol/operation/suboperation

Common route patterns include:

• /credential/offer - Credential issuance offer
• /credential/apply - Credential application request
• /credential/issue - Actual credential issuance
• /presentation/request - Presentation request
• /presentation/submit - Presentation submission

The route enables protocol multiplexing where different embedded protocols can coexist within the exn message framework.

Query/Payload (q)

The q field contains the embedded protocol data structure, which varies based on the route. For credential issuance:

{
  "issuer": "did:keri:EEBp64Aw2rsjdJpAR0e2qCq3jX7q7gLld3LjAwZgaLXU",
  "schema": "EckOnHB11J4H9q16I3tN8DdpNXnCiP5QJQ7yvkWqTDdA",
  "credential_manifest": { /* manifest structure */ }
}

The q field structure is protocol-specific and defined by the embedded protocol specification (IPEX, custom protocols, etc.).

Data Format

Field Definitions

Required Fields

All exn messages MUST include:

1. v (version): String, regexable KERI version identifier
2. t (type): String, must be "exn"
3. dt (datetime): String, ISO 8601 timestamp with timezone
4. r (route): String, hierarchical resource path
5. q (query/payload): Object, embedded protocol data

Optional Fields

Exn messages MAY include:

• a (attachments): Array of additional data structures
• e (edges): References to related messages or credentials
• Custom fields: Protocol-specific extensions

Encoding Format

Exn messages support multiple serialization formats:

JSON Serialization

The primary format for human-readable exchanges:

{
  "v": "KERI10JSON00011c_",
  "t": "exn",
  "dt": "2023-08-15T14:30:00.000000+00:00",
  "r": "/credential/offer",
  "q": {
    "issuer": "did:keri:EEBp64Aw2rsjdJpAR0e2qCq3jX7q7gLld3LjAwZgaLXU"
  }
}

CBOR Serialization

Binary format for compact transmission:

• Version string: KERI10CBOR000118_
• More efficient for bandwidth-constrained environments
• Maintains semantic equivalence with JSON

MGPK Serialization

MessagePack format for high-performance scenarios:

• Version string: KERI10MGPK000115_
• Optimized for speed and size
• Common in IoT and embedded systems

CESR Attachments

Exn messages include CESR-encoded cryptographic attachments appended after the message body:

-AABAA1o61PgMhwhi89FES_vwYeSbbWnVuELV_jv7Yv6f5zNiOLnj1ZZa4MW2c6Z_vZDt55QUnLaiaikE-d_ApsFEgCA

The attachment structure:

1. Count code: -AAB indicates attachment type and count
2. Sender AID: Fully qualified identifier of the sender
3. Signature(s): One or more cryptographic signatures

This format enables self-framing where the attachment length is determinable from the count code.

Size and Constraints

Message Size Limits

The version string's size indicator supports:

• Standard format: Up to 16,777,215 bytes (0xFFFFFF)
• Extended format: Larger messages via chunking protocols

Practical limits depend on:

• Transport layer constraints (HTTP, TCP, WebSocket)
• Witness and watcher processing capabilities
• Network bandwidth considerations

Field Constraints

• Version string: Fixed format, 17-20 characters
• Message type: Exactly 3 characters ("exn")
• Datetime: ISO 8601 format, typically 32 characters
• Route: Variable length, typically < 256 characters
• Query/payload: Variable, protocol-dependent

Operations

Creation and Initialization

Message Construction

Creating an exn message involves:

1. Determine route: Select appropriate protocol and operation
2. Construct payload: Build protocol-specific q structure
3. Generate timestamp: Create ISO 8601 datetime
4. Calculate size: Determine message body length
5. Format version string: Encode protocol, serialization, and size
6. Serialize message: Convert to chosen format (JSON/CBOR/MGPK)

Signature Generation

After message construction:

1. Compute digest: Hash the serialized message body
2. Sign digest: Use sender's current signing key(s)
3. Format attachment: Encode signature(s) in CESR format
4. Append attachment: Concatenate to message body

For multi-signature scenarios:

• Each participant signs independently
• Signatures are collected and aggregated
• Threshold requirements must be satisfied

Updates and Modifications

Message Immutability

Once signed, exn messages are cryptographically immutable:

• Any modification invalidates signatures
• Recipients detect tampering through signature verification
• Modified messages are rejected

This immutability is fundamental to KERI's security model.

Protocol Evolution

New message versions are created through:

1. Version string updates: Change protocol version identifier
2. Route extensions: Add new routes for new operations
3. Payload schema evolution: Extend q structure with new fields

Backward compatibility is maintained through:

• Version negotiation protocols
• Optional field handling
• Graceful degradation strategies

Verification and Validation

Structural Validation

Recipients perform multi-layer validation:

1. Version string parsing: Extract protocol, serialization, size
2. Size verification: Confirm message length matches version string
3. Type checking: Verify t field is "exn"
4. Datetime validation: Check timestamp format and range
5. Route validation: Verify route format and supported protocols
6. Payload validation: Check q structure against protocol schema

Cryptographic Verification

Signature verification involves:

1. Extract attachments: Parse CESR-encoded signatures
2. Identify sender: Resolve sender AID to current key state
3. Retrieve public keys: Query KEL for authoritative keys
4. Verify signatures: Validate each signature against message digest
5. Check thresholds: Ensure sufficient signatures for multi-sig

Temporal Validation

For replay attack protection:

1. Extract datetime: Parse dt field
2. Compare to current time: Check against acceptable window
3. Apply KRAM rules: Enforce replay protection policy
4. Reject stale messages: Discard messages outside window

The KRAM specification defines acceptable time windows based on:

• Clock drift tolerance
• Network latency estimates
• Security policy requirements

Usage Context

In Which Protocols

IPEX (Issuance and Presentation Exchange)

The primary use case for exn messages is IPEX protocol:

Credential Issuance Flow:

1. Offer (/credential/offer): Issuer proposes credential
2. Apply (/credential/apply): Holder requests credential
3. Issue (/credential/issue): Issuer delivers credential

Presentation Flow:

1. Request (/presentation/request): Verifier requests proof
2. Submit (/presentation/submit): Holder provides proof

Each step uses exn messages with protocol-specific payloads.

Custom Protocols

Organizations can define custom protocols using exn:

• Namespace routes: /org/protocol/operation
• Custom payloads: Organization-specific data structures
• Private exchanges: Bilateral communication patterns

This extensibility enables domain-specific applications while maintaining KERI security guarantees.

Multi-Signature Coordination

Exn messages facilitate multi-signature workflows:

• Proposal distribution: Share proposed actions with co-signers
• Signature collection: Gather signatures from participants
• Threshold satisfaction: Verify sufficient signatures collected

The MultisigIssuance documentation describes using exn messages for coordinating credential issuance among multiple issuers.

Lifecycle Management

Message Creation

Exn messages are created when:

• Initiating credential issuance
• Responding to presentation requests
• Exchanging arbitrary data between AIDs
• Coordinating multi-party operations

Message Transmission

Transmission occurs through:

• Direct connections: Peer-to-peer TCP/HTTP
• Witness mailboxes: Asynchronous message delivery
• Agent intermediaries: Cloud-based message routing

Message Storage

Exn messages may be stored:

• Temporarily: In mailboxes awaiting retrieval
• Permanently: In audit logs for compliance
• Selectively: Based on protocol requirements

Storage policies depend on:

• Regulatory requirements
• Business needs
• Privacy considerations

Related Structures

Key Event Log (KEL)

Exn messages depend on KELs for:

• Sender identity verification
• Public key resolution
• Key state validation

Without access to sender's KEL, recipients cannot verify exn message signatures.

Transaction Event Log (TEL)

For credential-related exn messages:

• TEL tracks credential issuance/revocation state
• Exn messages reference TEL entries
• Verifiers check TEL for credential status

ACDC Credentials

Exn messages transport ACDCs:

• Credential issuance embeds ACDC in q field
• Presentation includes ACDC references or full credentials
• Chained credentials create complex data structures

OOBI (Out-Of-Band Introduction)

OOBIs enable exn message exchange by:

• Providing initial endpoint discovery
• Establishing communication channels
• Resolving AIDs to network locations

Exn messages cannot be exchanged without prior OOBI resolution or pre-existing connections.

Security Considerations

Replay Attack Protection

The dt field combined with KRAM provides replay protection:

• Recipients maintain sliding time windows
• Messages outside windows are rejected
• Prevents attackers from reusing captured messages

Man-in-the-Middle Protection

CESR signature attachments provide end-to-end security:

• Messages are signed by sender's private key
• Recipients verify against sender's public key from KEL
• Intermediaries cannot forge or modify messages

Confidentiality

Exn messages provide authenticity but not confidentiality:

• Message content is not encrypted by default
• Sensitive data requires additional encryption layer
• SPAC (Secure Privacy, Authenticity, Confidentiality) protocols address this

Authorization

Exn messages enable authorization verification:

• Route specifies requested operation
• Recipient checks sender's authorization
• Access control policies determine acceptance

Implementation Patterns

Synchronous Exchange

For request-response patterns:

1. Sender creates exn message
2. Sender transmits to recipient
3. Recipient processes and responds
4. Sender receives response exn message

This pattern suits interactive protocols like credential presentation.

Asynchronous Exchange

For store-and-forward patterns:

1. Sender creates exn message
2. Sender deposits in recipient's mailbox
3. Recipient retrieves when online
4. Recipient processes and optionally responds

This pattern suits offline-capable scenarios like credential issuance.

Broadcast Exchange

For one-to-many patterns:

1. Sender creates exn message
2. Sender transmits to multiple recipients
3. Each recipient processes independently
4. Responses handled individually

This pattern suits notification scenarios.

Performance Considerations

Message Size Optimization

• Use compact serialization (CBOR/MGPK) for bandwidth efficiency
• Employ SAID references instead of embedding full credentials
• Implement compression for large payloads

Signature Verification Caching

• Cache public key lookups from KELs
• Reuse signature verification results within time windows
• Implement batch verification for multiple messages

Parallel Processing

• Process independent exn messages concurrently
• Use async I/O for network operations
• Implement worker pools for signature verification

Conclusion

The exn message type represents KERI's universal communication primitive, enabling secure, verifiable peer-to-peer exchanges while maintaining protocol extensibility. Its design balances:

• Security: Cryptographic signatures and replay protection
• Flexibility: Protocol-agnostic payload structure
• Efficiency: Multiple serialization formats and self-framing
• Interoperability: Standardized structure across implementations

Understanding exn messages is essential for implementing KERI-based applications, particularly those involving credential issuance and presentation through IPEX protocol.

Security Best Practices

1. Input Validation: Validate all fields before processing. Malformed messages should be rejected early to prevent resource exhaustion attacks.

2. Rate Limiting: Implement rate limiting on exn message acceptance to prevent denial-of-service attacks.

3. Confidentiality: For sensitive data, implement additional encryption layers (SPAC protocol) as exn messages provide authenticity but not confidentiality by default.

Testing Strategies

1. Test Vectors: Use the demo vectors in the keripy repository (src/keri/demo/vectors/) as reference implementations.

2. Interoperability Testing: Test against multiple KERI implementations (keripy, keriox, signify-ts) to ensure compatibility.

3. Failure Scenarios: Test handling of invalid signatures, expired timestamps, malformed payloads, and network failures.