BEP 15

For reference, the message flow defined in [BEP15] is as follows:

Client                        Tracker
  Connect Req. ------------->
    <-------------- Connect Resp.
  Announce Req. ------------->
    <-------------- Announce Resp.
  Announce Req. ------------->
    <-------------- Announce Resp.

The connect phase is required to prevent IP address spoofing. The tracker returns a connection ID that the client uses in subsequent announces. This connection ID expires by default in one minute at the client, and in two minutes at the tracker.

I2P will use the same message flow as BEP 15, for ease of adoption in existing UDP-capable client code bases: for efficiency, and for security reasons discussed below:

Client                        Tracker
  Connect Req. ------------->       (Repliable Datagram2)
    <-------------- Connect Resp.   (Raw)
  Announce Req. ------------->      (Repliable Datagram3)
    <-------------- Announce Resp.  (Raw)
  Announce Req. ------------->      (Repliable Datagram3)
    <-------------- Announce Resp.  (Raw)
           ...

This potentially provides a large bandwidth savings over streaming (TCP) announces. While the Datagram2 is about the same size as a streaming SYN, the raw response is much smaller than the streaming SYN ACK. Subsequent requests use Datagram3, and the subsequent responses are raw.

The announce requests are Datagram3 so that the tracker need not maintain a large mapping table of connection IDs to announce destination or hash. Instead, the tracker may generate connection IDs cryptographically from the sender hash, the current timestamp (based on some interval), and a secret value. When an announce request is received, the tracker validates the connection ID, and then uses the Datagram3 sender hash as the send target.

Connection Lifetime

[BEP15] specifies that the connection ID expires in one minute at the client, and in two minutes at the tracker. It is not configurable. That limits the potential efficiency gains, unless clients batched announces to do all of them within a one-minute window. i2psnark does not currently batch announces; it spreads them out, to avoid bursts of traffic. Power users are reported to be running thousands of torrents at once, and bursting that many announces into one minute is not realistic.

Here, we propose to extend the connect response to add an optional connection lifetime field. The default, if not present, is one minute. Otherwise, the lifetime specified in seconds, shall be used by the client, and the tracker will maintain the connection ID for one minute more.

Compatibility with BEP 15

This design maintains compatibility with [BEP15] as much as possible to limit changes required in existing clients and trackers.

The only required change is the format of peer info in the announce response. The addition of the lifetime field in the connect response is not required but is strongly recommended for efficiency, as explained above.

Security Analysis

An important goal of a UDP announce protocol is to prevent address spoofing. The client must actually exist and bundle a real leaseset. It must have inbound tunnels to receive the Connect Response. These tunnels could be zero-hop and built instantly, but that would expose the creator. This protocol accomplishes that goal.

Issues

• This protocol does not support blinded destinations, but may be extended to do so. See below.

Protocols and Ports

Repliable Datagram2 uses I2CP protocol 19; repliable Datagram3 uses I2CP protocol 20; raw datagrams use I2CP protocol 18. Requests may be Datagram2 or Datagram3. Responses are always raw. The older repliable datagram ("Datagram1") format using I2CP protocol 17 must NOT be used for requests or replies; these must be dropped if received on the request/reply ports. Note that Datagram1 protocol 17 is still used for the DHT protocol.

Requests use the I2CP "to port" from the announce URL; see below. The request "from port" is chosen by the client, but should be nonzero, and a different port from those used by DHT, so that responses may be easily classified. Trackers should reject requests received on the wrong port.

Responses use the I2CP "to port" from the request. The request "from port" is the "to port" from the request.

Announce URL

The announce URL format is not specified in [BEP15], but as in clearnet, UDP announce URLs are of the form "udp://host:port/path". The path is ignored and may be empty, but is typically "/announce" on clearnet. The :port part should always be present, however, if the ":port" part is omitted, use a default I2CP port of 6969, as that is the common port on clearnet. There may also be cgi parameters &a=b&c=d appended, those may be processed and provided in the announce request, see [BEP41]. If there are no parameters or path, the trailing / may also be omitted, as implied in [BEP41].

Datagram Formats

All values are send in network byte order (big endian). Do not expect packets to be exactly of a certain size. Future extensions could increase the size of packets.

Offset  Size            Name            Value
0       64-bit integer  protocol_id     0x41727101980 // magic constant
8       32-bit integer  action          0 // connect
12      32-bit integer  transaction_id

Offset  Size            Name            Value
0       32-bit integer  action          0 // connect
4       32-bit integer  transaction_id
8       64-bit integer  connection_id
16      16-bit integer  lifetime        optional  // Change from BEP 15

Offset  Size            Name            Value
0       64-bit integer  connection_id
8       32-bit integer  action          1     // announce
12      32-bit integer  transaction_id
16      20-byte string  info_hash
36      20-byte string  peer_id
56      64-bit integer  downloaded
64      64-bit integer  left
72      64-bit integer  uploaded
80      32-bit integer  event           0     // 0: none; 1: completed; 2: started; 3: stopped
84      32-bit integer  IP address      0     // default
88      32-bit integer  key
92      32-bit integer  num_want        -1    // default
96      16-bit integer  port
98      varies          options     optional  // As specified in BEP 41

Offset  Size            Name            Value
0           32-bit integer  action          1 // announce
4           32-bit integer  transaction_id
8           32-bit integer  interval
12          32-bit integer  leechers
16          32-bit integer  seeders
20   32 * n 32-byte hash    binary hashes     // Change from BEP 15
...                                           // Change from BEP 15

Offset  Size            Name            Value
0       32-bit integer  action          3 // error
4       32-bit integer  transaction_id
8       string          message

Clients

For a given tracker hostname, a client should prefer UDP over HTTP URLs, and should not announce to both.

Clients with existing BEP 15 support should require only small modifications.

If a client support DHT or other datagram protocols, it should probably select a different port as the request "from port" so that the replies come back to that port and are not mixed up with DHT messages. The client only receives raw datagrams as replies. Trackers will never send a repliable datagram2 to the client.

Clients with a default list of opentrackers should update the list to add UDP URLs after the known opentrackers are known to support UDP.

Clients may or may not implement retransmission of requests. Retransmissions, if implemented, should use an initial timeout of at least 15 seconds, and double the timeout for each retransmission (exponential backoff).

Clients must back off after receiving an error response.

Trackers

Trackers with existing BEP 15 support should require only small modifications. This specification differs from the 2014 proposal, in that the tracker must support reception of repliable datagram2 and datagram3 on the same port.

To minimize tracker resource requirements, this protocol is designed to eliminate any requirement that the tracker store mappings of client hashes to connection IDs for later validation. This is possible because the announce request packet is a repliable Datagram3 packet, so it contains the sender's hash.

A recommended implementation is:

• Define the current epoch as the current time with a resolution of the connection lifetime, epoch = now / lifetime.
• Define a cryptographic hash function H(secret, clienthash, epoch) which generates an 8 byte output.
• Generate the random constant secret used for all connections.
• For connect responses, generate connection_id = H(secret,  clienthash, epoch)
• For announce requests, validate the received connection ID in the current epoch by verifying connection_id == H(secret, clienthash, epoch) || connection_id == H(secret, clienthash, epoch - 1)