Datagrams

Overview

Datagrams provide message-oriented communication above I2CP and parallel to the streaming library.
They enable repliable, authenticated, or raw packets without requiring connection-oriented streams.
Routers encapsulate datagrams into I2NP messages and tunnel messages, regardless of whether NTCP2 or SSU2 carries the traffic.

The core motivation is to allow applications (like trackers, DNS resolvers, or games) to send self-contained packets that identify their sender.

New in 2025: The I2P Project approved Datagram2 (protocol 19) and Datagram3 (protocol 20), adding replay protection and lower-overhead repliable messaging for the first time in a decade.

1. Protocol Constants

Protocols 19 and 20 were formalized in Proposal 163 (April 2025).
They coexist with Datagram1 / RAW for backward compatibility.

2. Datagram Types

Typical Design Patterns

• Request → Response: Send a signed Datagram2 (request + nonce), receive a raw or Datagram3 reply (echo nonce).
• High-frequency/low-overhead: Prefer Datagram3 or RAW.
• Authenticated control messages: Datagram2.
• Legacy compatibility: Datagram1 still fully supported.

3. Datagram2 and Datagram3 Details (2025)

Datagram2 (Protocol 19)

Enhanced replacement for Datagram1.
Features:

• Replay prevention: 4-byte anti-replay token.
• Offline signature support: enables use by offline-signed Destinations.
• Expanded signature coverage: includes destination hash, flags, options, offline sig block, payload.
• Post-quantum ready: compatible with future ML-KEM hybrids.
• Overhead: ≈ 457 bytes (X25519 keys).

Datagram3 (Protocol 20)

Bridges gap between raw and signed types.
Features:

• Repliable without signature: contains sender’s 32-byte hash + 2-byte flags.
• Tiny overhead: ≈ 34 bytes.
• No replay defense — application must implement.

Both protocols are API 0.9.66 features and implemented in the Java router since Release 2.9.0; no i2pd or Go implementations yet (October 2025).

4. Size and Fragmentation Limits

• Tunnel message size: 1 028 bytes (4 B Tunnel ID + 16 B IV + 1 008 B payload).
• Initial fragment: 956 B (typical TUNNEL delivery).
• Follow-on fragment: 996 B.
• Max fragments: 63–64.
• Practical limit: ≈ 62 708 B (~61 KB).
• Recommended limit: ≤ 10 KB for reliable delivery (drops increase exponentially beyond this).

Overhead summary:

• Datagram1 ≈ 427 B (minimum).
• Datagram2 ≈ 457 B.
• Datagram3 ≈ 34 B.
• Additional layers (I2CP gzip header, I2NP, Garlic, Tunnel): + ~5.5 KB worst case.

5. I2CP / I2NP Integration

Message path:

1. Application creates datagram (via I2P API or SAM).
2. I2CP wraps with gzip header (0x1F 0x8B 0x08, RFC 1952) and CRC-32 checksum.
3. Protocol + Port numbers stored in gzip header fields.
4. Router encapsulates as I2NP message → Garlic clove → 1 KB tunnel fragments.
5. Fragments traverse outbound → network → inbound tunnel.
6. Reassembled datagram delivered to application handler based on protocol number.

Integrity: CRC-32 (from I2CP) + optional cryptographic signature (Datagram1/2).
There is no separate checksum field within the datagram itself.

6. Programming Interfaces

Java API

Package net.i2p.client.datagram includes:

• I2PDatagramMaker – builds signed datagrams.
• I2PDatagramDissector – verifies and extracts sender info.
• I2PInvalidDatagramException – thrown on verification failure.

I2PSessionMuxedImpl (net.i2p.client.impl.I2PSessionMuxedImpl) manages protocol and port multiplexing for apps sharing a Destination.

Javadoc access:

• idk.i2p Javadoc (I2P network only)
• Javadoc Mirror (clearnet mirror)
• Official Javadocs (official docs)

SAM v3 Support

• SAM 3.2 (2016): added PORT and PROTOCOL parameters.
• SAM 3.3 (2016): introduced PRIMARY/subsession model; allows streams + datagrams on one Destination.
• Support for Datagram2 / 3 session styles added spec 2025 (implementation pending).
• Official spec: SAM v3 Specification

i2ptunnel Modules

• udpTunnel: Fully functional base for I2P UDP apps (net.i2p.i2ptunnel.udpTunnel).
• streamr: Operational for A/V streaming (net.i2p.i2ptunnel.streamr).
• SOCKS UDP: Not functional as of 2.10.0 (UDP stub only).

For general-purpose UDP, use the Datagram API or udpTunnel directly—do not rely on SOCKS UDP.

7. Ecosystem and Language Support (2025)

Java I2P is the only router supporting full SAM 3.3 subsessions and Datagram2 API at this time.

8. Example Usage – UDP Tracker (I2PSnark 2.10.0)

First real-world application of Datagram2/3:

Pattern demonstrates mixed use of authenticated and lightweight datagrams to balance security and performance.

9. Security and Best Practices

• Use Datagram2 for any authenticated exchange or when replay attacks matter.
• Prefer Datagram3 for fast repliable responses with moderate trust.
• Use RAW for public broadcasts or anonymous data.
• Keep payloads ≤ 10 KB for reliable delivery.
• Be aware that SOCKS UDP remains non-functional.
• Always verify gzip CRC and digital signatures on receipt.

10. Technical Specification

This section covers the low-level datagram formats, encapsulation, and protocol details.

10.1 Protocol Identification

Datagram formats do not share a common header. Routers cannot infer the type from payload bytes alone.

When mixing multiple datagram types—or when combining datagrams with streaming—explicitly set:

• The protocol number (via I2CP or SAM)
• Optionally the port number, if your application multiplexes services

Leaving the protocol unset (0 or PROTO_ANY) is discouraged and may lead to routing or delivery errors.

10.2 Raw Datagrams

Non-repliable datagrams carry no sender or authentication data. They are opaque payloads, handled outside the higher-level datagram API but supported via SAM and I2PTunnel.

Protocol: 18 (PROTO_DATAGRAM_RAW)

Format:

+----+----+----+----+----//
|     payload...
+----+----+----+----+----//

Payload length is constrained by transport limits (≈32 KB practical max, often much less).

10.3 Datagram1 (Repliable Datagrams)

Embeds sender’s Destination and a Signature for authentication and reply addressing.

Protocol: 17 (PROTO_DATAGRAM)

Overhead: ≥427 bytes Payload: up to ~31.5 KB (limited by transport)

Format:

+----+----+----+----+----+----+----+----+
|               from                    |
+                                       +
|                                       |
~             Destination bytes         ~
|                                       |
+----+----+----+----+----+----+----+----+
|             signature                 |
+                                       +
|                                       |
+----+----+----+----+----+----+----+----+
|     payload...
+----+----+----+----//

• from: a Destination (387+ bytes)
• signature: a Signature matching the key type
  • For DSA_SHA1: Signature of the SHA-256 hash of the payload
  • For other key types: Signature directly over the payload

Notes:

• Signatures for non-DSA types were standardized in I2P 0.9.14.
• LS2 (Proposal 123) offline signatures are not currently supported in Datagram1.

10.4 Datagram2 Format

An improved repliable datagram that adds replay resistance as defined in Proposal 163.

Protocol: 19 (PROTO_DATAGRAM2)

Implementation is ongoing. Applications should include nonce or timestamp checks for redundancy.

10.5 Datagram3 Format

Provides repliable but unauthenticated datagrams. Relies on router-maintained session authentication rather than embedded destination and signature.

Protocol: 20 (PROTO_DATAGRAM3) Status: Under development since 0.9.66

Useful when:

• Destinations are large (e.g., post-quantum keys)
• Authentication occurs at another layer
• Bandwidth efficiency is critical

10.6 Data Integrity

Datagram integrity is protected by the gzip CRC-32 checksum in the I2CP layer. No explicit checksum field exists within the datagram payload format itself.

10.7 Packet Encapsulation

Each datagram is encapsulated as a single I2NP message or as an individual clove in a Garlic Message. I2CP, I2NP, and tunnel layers handle length and framing — there is no internal delimiter or length field in the datagram protocol.

10.8 Post-Quantum (PQ) Considerations

If Proposal 169 (ML-DSA signatures) is implemented, signature and destination sizes will rise dramatically — from ~455 bytes to ≥3739 bytes. This change will substantially increase datagram overhead and reduce effective payload capacity.

Datagram3, which relies on session-level authentication (not embedded signatures), will likely become the preferred design in post-quantum I2P environments.

11. References

• Proposal 163 – Datagram2 and Datagram3
• Proposal 160 – UDP Tracker Integration
• Proposal 144 – Streaming MTU Calculations
• Proposal 169 – Post-Quantum Signatures
• I2CP Specification
• I2NP Specification
• Tunnel Message Specification
• SAM v3 Specification
• i2ptunnel Documentation

12. Change Log Highlights (2019 – 2025)

13. Summary

The datagram subsystem now supports four protocol variants offering a spectrum from fully-authenticated to lightweight raw transmission.
Developers should migrate toward Datagram2 for security-sensitive use cases and Datagram3 for efficient repliable traffic.
All older types remain compatible to ensure long-term interoperability.