From 2ba24bb98528e86be722a09950016908987fccfa Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sun, 29 Mar 2020 06:21:37 -0700 Subject: [PATCH] Add description of UDP tracker protocol to book type: documentation --- .gitignore | 1 + book/book.toml | 3 + book/custom.css | 3 + book/src/SUMMARY.md | 1 + book/src/bep-support.md | 2 + book/src/udp-tracker-protocol.md | 198 +++++++++++++++++++++++++++++++ 6 files changed, 208 insertions(+) create mode 100644 book/custom.css create mode 100644 book/src/udp-tracker-protocol.md diff --git a/.gitignore b/.gitignore index 1af1e63..be43c3c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /target **/*.rs.bk /www/book +/book/book /wiki diff --git a/book/book.toml b/book/book.toml index 62d7ba4..d082f45 100644 --- a/book/book.toml +++ b/book/book.toml @@ -4,3 +4,6 @@ language = "en" multilingual = false src = "src" title = "Intermodal" + +[output.html] +additional-css = ["custom.css"] diff --git a/book/custom.css b/book/custom.css new file mode 100644 index 0000000..9c62dd1 --- /dev/null +++ b/book/custom.css @@ -0,0 +1,3 @@ +table { + margin: 0; +} diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 09fde36..360f9d2 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -6,3 +6,4 @@ Summary - [BitTorrent BEP Support](./bep-support.md) - [Alternatives & Prior Art](./prior-art.md) - [BitTorrent References](./bittorrent-references.md) +- [UDP Tracker Protocol](./udp-tracker-protocol.md) diff --git a/book/src/bep-support.md b/book/src/bep-support.md index 375eba7..f6c2e16 100644 --- a/book/src/bep-support.md +++ b/book/src/bep-support.md @@ -7,6 +7,8 @@ BEP Support | ❌ | Unsupported (link to issue) | | ➖ | Not Applicable | +
+ | BEP | Status | Title | |:----------------------------------------------:|:----------------------------------------------------------:|:-----------------------------------------------------------------| | [00](http://bittorrent.org/beps/bep_0000.html) | ➖ | Index of BitTorrent Enhancement Proposals | diff --git a/book/src/udp-tracker-protocol.md b/book/src/udp-tracker-protocol.md new file mode 100644 index 0000000..83cfae2 --- /dev/null +++ b/book/src/udp-tracker-protocol.md @@ -0,0 +1,198 @@ +Bittorrent UDP-tracker protocol +=============================== + +This description of the UDP tracker protocol is adapted from +[this page](https://libtorrent.org/udp_tracker_protocol.html) by Arvid Norberg. + +A tracker with the protocol "udp://" in its URI is should be contacted with +this protocol. + +All values are sent in network byte order (big-endian). + +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. + +Transaction IDs sent in request messages are returned in response messages. + +Connection ID returned by tracker in connect response message should be sent +by client in later requests. The initial connection ID sent in connect requests +shoudl be `0x41727101980` in network byte order. + +Action values in requests and responses should be taken from the `Actions` +table. + +When a message is followed by a structure labeled _repeating:_, the rest of the +message is zero or more of that structure. + + +Actions +------- + +| name | value | +|----------|-------| +| connect | 0 | +| announce | 1 | +| scrape | 2 | +| error | 3 | + +Events +------ + +| name | value | +|-----------|-------| +| none | 0 | +| completed | 1 | +| started | 2 | +| stopped | 3 | + +Error +------ + +| size | name | description | +|------|----------------|-------------------------------------------| +| i32 | action | | +| i32 | transaction_id | | +| i8[] | error_string | rest of packet is string describing error | + +Connect +------- + +### Request + +| type | name | +|------|----------------| +| i64 | connection_id | +| i32 | action | +| i32 | transaction_id | + +### Response + +| type | name | +|------|----------------| +| i32 | action | +| i32 | transaction_id | +| i64 | connection_id | + +Announce +-------- + +### Request + +| type | name | description | +|----------|----------------|--------------------------------------------------------------| +| i64 | connection_id | | +| i32 | action | | +| i32 | transaction_id | | +| [i8; 20] | info_hash | torrent infohash | +| [i8; 20] | peer_id | peer ID | +| i64 | downloaded | bytes downloaded this session | +| i64 | left | bytes left to download | +| i64 | uploaded | bytes uploaded this session | +| i32 | event | from `Events` table | +| u32 | ip | 0 to use sender of this UDP packet | +| u32 | key | randomly generated by client, unknown function. | +| i32 | num_want | maximum number of peers to send in reply, use -1 for default | +| u16 | port | listening port | +| u16 | extensions | | + +### Response + +| type | name | description | +|------|----------------|-------------------------------------------------------------| +| i32 | action | | +| i32 | transaction_id | | +| i32 | interval | seconds to wait announcing again | +| i32 | leechers | number of peers in swarm that have not finished downloading | +| i32 | seeders | number of peers in swarm that have finished downloading | + +_repeating:_ + +| type | name | description | +|------|------|---------------------| +| i32 | ip | peer IP | +| i16 | port | peer listening port | + +Scrape +------ + +### Request + +| size | name | +|------|----------------| +| i64 | connection_id | +| i32 | action | +| i32 | transaction_id | + +_repeating:_ + +| size | name | +|----------|-----------| +| [i8; 20] | info_hash | + +### Response + +| size | name | +|------|----------------| +| i32 | action | +| i32 | transaction_id | + +_repeating:_ + +| size | name | description | +|------|------------|----------------------------------------------| +| i32 | complete | peers in swarm that have finished downloding | +| i32 | downloaded | times torrent has been downloaded | +| i32 | incomplete | peers that have not finished downloading | + +Extensions +---------- + +The extensions field is a bitmask. The following bits are assigned: + +| name | bit | +|----------------|-----| +| authentication | 1 | +| request string | 2 | + +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 authentication information appended to it. + +`passwd_hash` is the first eight bytes of `sha1(packet || sha1(password))`, +where `packet` is the bytes of the packet, less the final 8 bytes that are +`passwd_hash`. + +| size | name | description | +|-------|-----------------|-----------------------------------| +| i8 | username_length | | +| i8[] | username | length given by `username_length` | +| u8[8] | passwd_hash | | + +### 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 | +|------|----------------|----------------------------------| +| i8 | request_length | | +| i8[] | request_string | length given by `request_length` | + +`request_string` is the string that comes after the hostname 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