twisterp2pnetworkbittorrentblockchainipv6microbloggingdecentralizedsocial-networkdhttwister-ipv6twister-coretwisterarmyp2p-networktwister-server
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
320 lines
17 KiB
320 lines
17 KiB
Bittorrent udp-tracker protocol extension |
|
========================================= |
|
|
|
:Author: Arvid Norberg, arvid@rasterbar.com |
|
|
|
.. contents:: Table of contents |
|
:depth: 2 |
|
:backlinks: none |
|
|
|
|
|
introduction |
|
------------ |
|
|
|
A tracker with the protocol "udp://" in its URI |
|
is supposed to be contacted using this protocol. |
|
|
|
This protocol is supported by |
|
xbt-tracker_. |
|
|
|
|
|
.. _xbt-tracker: http://xbtt.sourceforge.net |
|
|
|
For additional information and descritptions of |
|
the terminology used in this document, see |
|
the `protocol specification`__ |
|
|
|
__ http://wiki.theory.org/index.php/BitTorrentSpecification |
|
|
|
All values are sent in network byte order (big endian). The sizes |
|
are specified with ANSI-C standard types. |
|
|
|
If no response to a request is received within 15 seconds, resend |
|
the request. If no reply has been received after 60 seconds, stop |
|
retrying. |
|
|
|
|
|
connecting |
|
---------- |
|
|
|
Client sends packet: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int64_t | connection_id | Must be initialized to 0x41727101980 | |
|
| | | in network byte order. This will | |
|
| | | identify the protocol. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | action | 0 for a connection request | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | transaction_id | Randomized by client. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
Server replies with packet: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int32_t | action | Describes the type of packet, in this | |
|
| | | case it should be 0, for connect. | |
|
| | | If 3 (for error) see errors_. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | transaction_id | Must match the transaction_id sent | |
|
| | | from the client. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int64_t | connection_id | A connection id, this is used when | |
|
| | | further information is exchanged with | |
|
| | | the tracker, to identify you. | |
|
| | | This connection id can be reused for | |
|
| | | multiple requests, but if it's cached | |
|
| | | for too long, it will not be valid | |
|
| | | anymore. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
|
|
announcing |
|
---------- |
|
|
|
Client sends packet: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int64_t | connection_id | The connection id acquired from | |
|
| | | establishing the connection. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | action | Action. in this case, 1 for announce. | |
|
| | | See actions_. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | transaction_id | Randomized by client. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int8_t[20] | info_hash | The info-hash of the torrent you want | |
|
| | | announce yourself in. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int8_t[20] | peer_id | Your peer id. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int64_t | downloaded | The number of byte you've downloaded | |
|
| | | in this session. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int64_t | left | The number of bytes you have left to | |
|
| | | download until you're finished. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int64_t | uploaded | The number of bytes you have uploaded | |
|
| | | in this session. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | event | The event, one of | |
|
| | | | |
|
| | | * none = 0 | |
|
| | | * completed = 1 | |
|
| | | * started = 2 | |
|
| | | * stopped = 3 | |
|
+-------------+---------------------+----------------------------------------+ |
|
| uint32_t | ip | Your ip address. Set to 0 if you want | |
|
| | | the tracker to use the ``sender`` of | |
|
| | | this udp packet. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| uint32_t | key | A unique key that is randomized by the | |
|
| | | client. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | num_want | The maximum number of peers you want | |
|
| | | in the reply. Use -1 for default. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| uint16_t | port | The port you're listening on. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| uint16_t | extensions | See extensions_ | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
|
|
Server replies with packet: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int32_t | action | The action this is a reply to. Should | |
|
| | | in this case be 1 for announce. | |
|
| | | If 3 (for error) see errors_. | |
|
| | | See actions_. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | transaction_id | Must match the transaction_id sent | |
|
| | | in the announce request. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | interval | the number of seconds you should wait | |
|
| | | until reannouncing yourself. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | leechers | The number of peers in the swarm that | |
|
| | | has not finished downloading. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | seeders | The number of peers in the swarm that | |
|
| | | has finished downloading and are | |
|
| | | seeding. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
The rest of the server reply is a variable number of the following structure: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int32_t | ip | The ip of a peer in the swarm. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| uint16_t | port | The peer's listen port. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
|
|
scraping |
|
-------- |
|
|
|
Client sends packet: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int64_t | connection_id | The connection id retreived from the | |
|
| | | establishing of the connection. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | action | The action, in this case, 2 for | |
|
| | | scrape. See actions_. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | transaction_id | Randomized by client. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
The following structure is repeated for each info-hash to scrape, but limited by |
|
the MTU. |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int8_t[20] | info_hash | The info hash that is to be scraped. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
|
|
Server replies with packet: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int32_t | action | The action, should in this case be | |
|
| | | 2 for scrape. | |
|
| | | If 3 (for error) see errors_. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | transaction_id | Must match the sent transaction id. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
The rest of the packet contains the following structures once for each info-hash |
|
you asked in the scrape request. |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int32_t | complete | The current number of connected seeds. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | downloaded | The number of times this torrent has | |
|
| | | been downloaded. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | incomplete | The current number of connected | |
|
| | | leechers. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
|
|
errors |
|
------ |
|
|
|
In case of a tracker error, |
|
|
|
server replies packet: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int32_t | action | The action, in this case 3, for error. | |
|
| | | See actions_. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int32_t | transaction_id | Must match the transaction_id sent | |
|
| | | from the client. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int8_t[] | error_string | The rest of the packet is a string | |
|
| | | describing the error. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
|
|
actions |
|
------- |
|
|
|
The action fields has the following encoding: |
|
|
|
* connect = 0 |
|
* announce = 1 |
|
* scrape = 2 |
|
* error = 3 (only in server replies) |
|
|
|
|
|
extensions |
|
---------- |
|
|
|
The extensions field is a bitmask. The following |
|
bits are assigned: |
|
|
|
* 1 = authentication_. |
|
* 2 = `request string`_. |
|
|
|
If multiple bits are present in the extension field, the extension |
|
bodies are appended to the packet in the order of least significant |
|
bit first. For instance, if both bit 1 and 2 are set, the extension |
|
represented by bit 1 comes first, followed by the extension represented |
|
by bit 2. |
|
|
|
authentication |
|
~~~~~~~~~~~~~~ |
|
|
|
The packet will have an authentication part |
|
appended to it. It has the following format: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int8_t | username_length | The number of characters in the | |
|
| | | username. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int8_t[] | username | The username, the number of characters | |
|
| | | as specified in the previous field. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| uint8_t[8] | passwd_hash | sha1(packet + sha1(password)) | |
|
| | | The packet in this case means the | |
|
| | | entire packet except these 8 bytes | |
|
| | | that are the password hash. These are | |
|
| | | the 8 first bytes (most significant) | |
|
| | | from the 20 bytes hash calculated. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
request string |
|
-------------- |
|
|
|
The request string extension is meant to allow torrent creators pass along |
|
cookies back to the tracker. This can be useful for authenticating that a |
|
torrent is allowed to be tracked by a tracker for instance. It could also |
|
be used to authenticate users by generating torrents with unique tokens |
|
in the tracker URL for each user. The extension body has the following format: |
|
|
|
+-------------+---------------------+----------------------------------------+ |
|
| size | name | description | |
|
+=============+=====================+========================================+ |
|
| int8_t | request length | The number of bytes in the request | |
|
| | | string. | |
|
+-------------+---------------------+----------------------------------------+ |
|
| int8_t[] | request string | The string that comes after the host- | |
|
| | | name and port in the udp tracker URL. | |
|
| | | Typically this starts with "/announce" | |
|
| | | The bittorrent client is not expected | |
|
| | | to append query string arguments for | |
|
| | | stats reporting, like "uploaded" and | |
|
| | | "downloaded" since this is already | |
|
| | | reported in the udp tracker protocol. | |
|
| | | However, the client is free to add | |
|
| | | arguments as extensions. | |
|
+-------------+---------------------+----------------------------------------+ |
|
|
|
credits |
|
------- |
|
|
|
Protocol designed by Olaf van der Spek and extended by Arvid Norberg |
|
|
|
|