Overview
Pulled out from [Prop123] as a separate proposal.
Offline signatures cannot be verified in the repliable datagram processing. Needs a flag to indicate offline signed but there's no place to put a flag.
Will require a completely new I2CP protocol number and format, to be added to the [DATAGRAMS] specification. Let's call it "Datagram2".
Motivation
Left over from LS2 work otherwise completed in 2019.
The first application to use Datagram2 is expected to be bittorrent UDP announces, as implemented in i2psnark and zzzot, see [Prop160].
Repliable Datagram Spec
For reference, following is a review of the specification for repliable datagrams, copied from [Datagrams]. The standard I2CP protocol number for repliable datagrams is PROTO_DATAGRAM (17).
+----+----+----+----+----+----+----+----+
| from |
+ +
| |
~ ~
~ ~
| |
+ +
| |
| |
+----+----+----+----+----+----+----+----+
| signature |
+ +
| |
+ +
| |
+ +
| |
+ +
| |
+----+----+----+----+----+----+----+----+
| payload...
+----+----+----+----//
from :: a Destination
length: 387+ bytes
The originator and signer of the datagram
signature :: a Signature
Signature type must match the signing public key type of $from
length: 40+ bytes, as implied by the Signature type.
For the default DSA_SHA1 key type:
The DSA Signature of the SHA-256 hash of the payload.
For other key types:
The Signature of the payload.
The signature may be verified by the signing public key of $from
payload :: The data
Length: 0 to about 31.5 KB (see notes)
Total length: Payload length + 427+
Design
- Define new protocol 19 - Repliable datagram with options.
- Add flags field for offline signatures and future expansion
- Move signature after the payload for easier processing
- New signature specification different from repliable datagram or streaming, so that signature verification will fail if interpreted as repliable datagram or streaming. This is accomplished by moving the signature after the payload, and by adding a prelude to the signature function.
- Add replay prevention as in [Prop164] for streaming.
- Reuse offline signature format from [Common] and [Streaming].
- Offline signature section must be before the variable-length payload and signature sections, as it specifies the length of the signature.
Specification
Protocol
The new I2CP protocol number for Datagram2 is 19. Add it as PROTO_DATAGRAM2 to [I2CP].
Format
Add Datagram2 to [DATAGRAMS] as follows:
+----+----+----+----+----+----+----+----+
| |
~ from ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| flags | tohash | |
+----+----+----+----+----+----+ +
| |
~ offline_signature (optional) ~
~ expires, sigtype, pubkey, offsig ~
| |
+----+----+----+----+----+----+----+----+
| |
~ payload ~
~ ~
| |
+----+----+----+----+----+----+----+----+
| |
~ signature ~
~ ~
| |
+----+----+----+----+----+----+----+----+
from :: a Destination
length: 387+ bytes
The originator and (unless offline signed) signer of the datagram
flags :: (2 bytes)
Bit order: 15 14 ... 3 2 1 0
Bits 3-0: Version: 0x02 (0 0 1 0)
Bit 4: If 0, no offline sig; if 1, offline signed
Bits 15-5: unused, set to 0 for compatibility with future uses
tohash :: (4 bytes)
The first 4 bytes of the target destination, for replay prevention
offline_signature ::
If flag indicates offline keys, the offline signature section,
as specified in the Common Structures Specification,
with the following 4 fields. Length: varies by online and offline
sig types, typically 102 bytes for Ed25519
This section can, and should, be generated offline.
expires :: Expires timestamp
(4 bytes, big endian, seconds since epoch, rolls over in 2106)
sigtype :: Transient sig type (2 bytes, big endian)
pubkey :: Transient signing public key (length as implied by sig type),
typically 32 bytes for Ed25519 sig type.
offsig :: a Signature
Signature of expires timestamp, transient sig type,
and public key, by the destination public key,
length: 40+ bytes, as implied by the Signature type, typically
64 bytes for Ed25519 sig type.
payload :: The data
Length: 0 to about 61 KB (see notes)
signature :: a Signature
Signature type must match the signing public key type of $from
(if no offline signature) or the transient sigtype
(if offline signed)
length: 40+ bytes, as implied by the Signature type, typically
64 bytes for Ed25519 sig type.
The Signature of the payload and other fields as specified below.
The signature is verified by the signing public key of $from
(if no offline signature) or the transient pubkey
(if offline signed)
Total length: minimum 433 + payload length; typical length for X25519 senders and without offline signatures: 461 + payload length. Note that the message will typically be compressed with gzip at the I2CP layer, which will result in significant savings if the from destination is compressible.
Note: The offline signature format is the same as in the Common Structures spec [Common] and [Streaming].
Signatures
The signature is over the following fields.
- Prelude: "Datagram2Prelude" (not included in the datagram)
- flags
- tohash
- offline_signature (if present)
- payload
In repliable datagram, for the DSA_SHA1 key type, the signature was over the SHA-256 hash of the payload, not the payload itself; here, the signature is always over the fields above (NOT the hash), regardless of key type.
ToHash Verification
Receivers must verify that the tohash field matches the first four bytes of their destination hash, and discard on mismatch, for replay prevention.
SAM
Add STYLE=DATAGRAM2 to the SAMv3 specification. Update the information on offline signatures.
Overhead
This design adds 6 bytes of overhead to repliable datagrams; 2 for flags and 4 for replay prevention. This is acceptable.
Security Analysis
Four bytes for the hash prefix should be sufficient?
Notes
- The practical length is limited by lower layers of protocols - the tunnel message spec [TUNMSG] limits messages to about 61.2 KB and the transports [TRANSPORT] currently limit messages to about 64 KB, so the data length here is limited to about 61 KB.
- See important notes about the reliability of large datagrams [API]. For best results, limit the payload to about 10 KB or less.
Compatibility
None. Applications must be rewritten to route Datagram2 I2CP messages based on protocol and/or port. Datagram2 messages that are misrouted and interpreted as Repliable datagram or streaming messages will fail based on signature, format, or both.
Migration
Each UDP application must separately detect support and migrate. The most prominent UDP application is bittorrent.
Bittorrent
Bittorrent DHT: Needs extension flag probably, e.g. i2p_dg2, coordinate with BiglyBT
Bittorrent UDP Announces [Prop160]: Design in from the beginning. Coordindate with BiglyBT, i2psnark, zzzot
Others
Bote: Unlikely to migrate, not actively maintained
Streamr: Nobody's using it, no migration planned
SAM UDP apps: None known
References
| [API] | http://i2project.net/en/docs/api/datagrams |
| [BT-SPEC] | http://i2project.net/en/docs/applications/bittorrent |
| [Common] | (1, 2) http://i2project.net/spec/common-structures |
| [DATAGRAMS] | (1, 2, 3) http://i2project.net/spec/datagrams |
| [I2CP] | http://i2project.net/en/docs/protocol/i2cp |
| [Prop123] | http://i2project.net/spec/proposals/123-new-netdb-entries |
| [Prop160] | (1, 2) http://i2project.net/spec/proposals/160-udp-trackers |
| [Prop164] | http://i2project.net/spec/proposals/164-streaming |
| [Streaming] | (1, 2) http://i2project.net/spec/streaming |
| [TRANSPORT] | http://i2project.net/en/docs/transport |
| [TUNMSG] | http://i2project.net/spec/tunnel-message#notes |