| 1 | <?xml version="1.0" encoding="utf-8" ?> |
|---|
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
|---|
| 4 | <head> |
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|---|
| 6 | <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" /> |
|---|
| 7 | <title></title> |
|---|
| 8 | <link rel="stylesheet" href="../css/bep.css" type="text/css" /> |
|---|
| 9 | </head> |
|---|
| 10 | <body> |
|---|
| 11 | <div class="document"> |
|---|
| 12 | |
|---|
| 13 | <div id="upper" class="clear"> |
|---|
| 14 | <div id="wrap"> |
|---|
| 15 | <div id="header"> |
|---|
| 16 | <h1><a href="../index.html">BitTorrent<span>.org</span></a></h1> |
|---|
| 17 | </div> |
|---|
| 18 | <div id="nav"> |
|---|
| 19 | <ul> |
|---|
| 20 | <li><a href="../index.html">Home</a></li> |
|---|
| 21 | <li><a href="../introduction.html">For Users</a></li> |
|---|
| 22 | <li><span>For Developers</span></li> |
|---|
| 23 | <!-- <li><a href="./blog">Blog</a></li> --> |
|---|
| 24 | <li><a href="../donate.html">Donate!</a></li> |
|---|
| 25 | </ul> |
|---|
| 26 | </div> <!-- nav --> |
|---|
| 27 | <!-- ### Begin Content ### --> |
|---|
| 28 | <div id="second"> |
|---|
| 29 | |
|---|
| 30 | |
|---|
| 31 | |
|---|
| 32 | <table class="rfc2822 docutils field-list" frame="void" rules="none"> |
|---|
| 33 | <col class="field-name" /> |
|---|
| 34 | <col class="field-body" /> |
|---|
| 35 | <tbody valign="top"> |
|---|
| 36 | <tr class="field"><th class="field-name">BEP:</th><td class="field-body">10</td> |
|---|
| 37 | </tr> |
|---|
| 38 | <tr class="field"><th class="field-name">Title:</th><td class="field-body">Extension Protocol</td> |
|---|
| 39 | </tr> |
|---|
| 40 | <tr class="field"><th class="field-name">Version:</th><td class="field-body">10848</td> |
|---|
| 41 | </tr> |
|---|
| 42 | <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_0010.rst">2008-02-15 14:53:10 -0800 (Fri, 15 Feb 2008)</a></td> |
|---|
| 43 | </tr> |
|---|
| 44 | <tr class="field"><th class="field-name">Author:</th><td class="field-body">Arvid Norberg <arvid at bittorrent.com>, Ludvig Strigeus <bittorrent at strigeus.com>, Greg Hazel <greg at bittorrent.com></td> |
|---|
| 45 | </tr> |
|---|
| 46 | <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td> |
|---|
| 47 | </tr> |
|---|
| 48 | <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> |
|---|
| 49 | </tr> |
|---|
| 50 | <tr class="field"><th class="field-name">Created:</th><td class="field-body">31-Jan-2008</td> |
|---|
| 51 | </tr> |
|---|
| 52 | <tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td> |
|---|
| 53 | </tr> |
|---|
| 54 | </tbody> |
|---|
| 55 | </table> |
|---|
| 56 | <hr /> |
|---|
| 57 | <div class="contents topic" id="contents"> |
|---|
| 58 | <p class="topic-title first">Contents</p> |
|---|
| 59 | <ul class="simple"> |
|---|
| 60 | <li><a class="reference internal" href="#handshake-message" id="id2">handshake message</a></li> |
|---|
| 61 | <li><a class="reference internal" href="#rationale" id="id3">rationale</a></li> |
|---|
| 62 | </ul> |
|---|
| 63 | </div> |
|---|
| 64 | <p>The intention of this protocol is to provide a simple and thin transport |
|---|
| 65 | for extensions to the bittorrent protocol. Supporting this protocol makes |
|---|
| 66 | it easy to add new extensions without interfering with the standard |
|---|
| 67 | bittorrent protocol or clients that don't support this extension or the |
|---|
| 68 | one you want to add.</p> |
|---|
| 69 | <p>To advertise to other clients that you support, one bit from the reserved |
|---|
| 70 | bytes is used.</p> |
|---|
| 71 | <p>The bit selected for the extension protocol is bit 20 from the right (counting |
|---|
| 72 | starts at 0). So (reserved_byte[5] & 0x10) is the expression to use for checking |
|---|
| 73 | if the client supports extended messaging.</p> |
|---|
| 74 | <p>Once support for the protocol is established, the client is supposed to |
|---|
| 75 | support 1 new message:</p> |
|---|
| 76 | <table border="1" class="docutils"> |
|---|
| 77 | <colgroup> |
|---|
| 78 | <col width="86%" /> |
|---|
| 79 | <col width="14%" /> |
|---|
| 80 | </colgroup> |
|---|
| 81 | <thead valign="bottom"> |
|---|
| 82 | <tr><th class="head">name</th> |
|---|
| 83 | <th class="head">id</th> |
|---|
| 84 | </tr> |
|---|
| 85 | </thead> |
|---|
| 86 | <tbody valign="top"> |
|---|
| 87 | <tr><td><tt class="docutils literal"><span class="pre">extended</span></tt></td> |
|---|
| 88 | <td>20</td> |
|---|
| 89 | </tr> |
|---|
| 90 | </tbody> |
|---|
| 91 | </table> |
|---|
| 92 | <p>This message is sent as any other bittorrent message, with a 4 byte length |
|---|
| 93 | prefix and a single byte identifying the message (the single byte being 20 |
|---|
| 94 | in this case). At the start of the payload of the message, is a single byte |
|---|
| 95 | message identifier. This identifier can refer to different extension messages |
|---|
| 96 | and only one ID is specified, 0. If the ID is 0, the message is a handshake |
|---|
| 97 | message which is described below. The layout of a general <tt class="docutils literal"><span class="pre">extended</span></tt> message |
|---|
| 98 | follows (including the message headers used by the bittorrent protocol):</p> |
|---|
| 99 | <table border="1" class="docutils"> |
|---|
| 100 | <colgroup> |
|---|
| 101 | <col width="15%" /> |
|---|
| 102 | <col width="85%" /> |
|---|
| 103 | </colgroup> |
|---|
| 104 | <thead valign="bottom"> |
|---|
| 105 | <tr><th class="head">size</th> |
|---|
| 106 | <th class="head">description</th> |
|---|
| 107 | </tr> |
|---|
| 108 | </thead> |
|---|
| 109 | <tbody valign="top"> |
|---|
| 110 | <tr><td>uint32_t</td> |
|---|
| 111 | <td>length prefix. Specifies the number of bytes for the |
|---|
| 112 | entire message. (Big endian)</td> |
|---|
| 113 | </tr> |
|---|
| 114 | <tr><td>uint8_t</td> |
|---|
| 115 | <td>bittorrent message ID, = 20</td> |
|---|
| 116 | </tr> |
|---|
| 117 | <tr><td>uint8_t</td> |
|---|
| 118 | <td>extended message ID. 0 = handshake, >0 = extended |
|---|
| 119 | message as specified by the handshake.</td> |
|---|
| 120 | </tr> |
|---|
| 121 | </tbody> |
|---|
| 122 | </table> |
|---|
| 123 | <div class="section" id="handshake-message"> |
|---|
| 124 | <h1>handshake message</h1> |
|---|
| 125 | <p>The payload of the handshake message is a bencoded dictionary. All items |
|---|
| 126 | in the dictionary are optional. Any unknown names should be ignored |
|---|
| 127 | by the client. All parts of the dictionary are case sensitive. |
|---|
| 128 | This is the defined item in the dictionary:</p> |
|---|
| 129 | <table border="1" class="docutils"> |
|---|
| 130 | <colgroup> |
|---|
| 131 | <col width="11%" /> |
|---|
| 132 | <col width="89%" /> |
|---|
| 133 | </colgroup> |
|---|
| 134 | <thead valign="bottom"> |
|---|
| 135 | <tr><th class="head">name</th> |
|---|
| 136 | <th class="head">description</th> |
|---|
| 137 | </tr> |
|---|
| 138 | </thead> |
|---|
| 139 | <tbody valign="top"> |
|---|
| 140 | <tr><td>m</td> |
|---|
| 141 | <td><p class="first">Dictionary of supported extension messages which maps |
|---|
| 142 | names of extensions to an extended message ID for each |
|---|
| 143 | extension message. The only requirement on these IDs |
|---|
| 144 | is that no extension message share the same one. Setting |
|---|
| 145 | an extension number to zero means that the extension is |
|---|
| 146 | not supported/disabled. The client should ignore any |
|---|
| 147 | extension names it doesn't recognize.</p> |
|---|
| 148 | <p class="last">The extension message IDs are the IDs used to send the |
|---|
| 149 | extension messages to the peer sending this handshake. |
|---|
| 150 | i.e. The IDs are local to this particular peer.</p> |
|---|
| 151 | </td> |
|---|
| 152 | </tr> |
|---|
| 153 | </tbody> |
|---|
| 154 | </table> |
|---|
| 155 | <p>Here are some other items that an implementation may choose to support:</p> |
|---|
| 156 | <table border="1" class="docutils"> |
|---|
| 157 | <colgroup> |
|---|
| 158 | <col width="12%" /> |
|---|
| 159 | <col width="88%" /> |
|---|
| 160 | </colgroup> |
|---|
| 161 | <thead valign="bottom"> |
|---|
| 162 | <tr><th class="head">name</th> |
|---|
| 163 | <th class="head">description</th> |
|---|
| 164 | </tr> |
|---|
| 165 | </thead> |
|---|
| 166 | <tbody valign="top"> |
|---|
| 167 | <tr><td>p</td> |
|---|
| 168 | <td>Local TCP listen port. Allows each side to learn about |
|---|
| 169 | the TCP port number of the other side. Note that there is |
|---|
| 170 | no need for the receiving side of the connection to send |
|---|
| 171 | this extension message, since its port number is already |
|---|
| 172 | known.</td> |
|---|
| 173 | </tr> |
|---|
| 174 | <tr><td>v</td> |
|---|
| 175 | <td>Client name and version (as a utf-8 string). |
|---|
| 176 | This is a much more reliable way of identifying the |
|---|
| 177 | client than relying on the peer id encoding.</td> |
|---|
| 178 | </tr> |
|---|
| 179 | <tr><td>yourip</td> |
|---|
| 180 | <td>A string containing the compact representation of the ip |
|---|
| 181 | address this peer sees you as. i.e. this is the |
|---|
| 182 | receiver's external ip address (no port is included). |
|---|
| 183 | This may be either an IPv4 (4 bytes) or an IPv6 |
|---|
| 184 | (16 bytes) address.</td> |
|---|
| 185 | </tr> |
|---|
| 186 | <tr><td>ipv6</td> |
|---|
| 187 | <td>If this peer has an IPv6 interface, this is the compact |
|---|
| 188 | representation of that address (16 bytes). The client may |
|---|
| 189 | prefer to connect back via the IPv6 address.</td> |
|---|
| 190 | </tr> |
|---|
| 191 | <tr><td>ipv4</td> |
|---|
| 192 | <td>If this peer has an IPv4 interface, this is the compact |
|---|
| 193 | representation of that address (4 bytes). The client may |
|---|
| 194 | prefer to connect back via this interface.</td> |
|---|
| 195 | </tr> |
|---|
| 196 | <tr><td>reqq</td> |
|---|
| 197 | <td>An integer, the number of outstanding request messages |
|---|
| 198 | this client supports without dropping any. The default in |
|---|
| 199 | in libtorrent is 250.</td> |
|---|
| 200 | </tr> |
|---|
| 201 | </tbody> |
|---|
| 202 | </table> |
|---|
| 203 | <p>The handshake dictionary could also include extended handshake |
|---|
| 204 | information, such as support for encrypted headers or anything |
|---|
| 205 | imaginable.</p> |
|---|
| 206 | <p>An example of what the payload of a handshake message could look like:</p> |
|---|
| 207 | <table border="1" class="docutils"> |
|---|
| 208 | <colgroup> |
|---|
| 209 | <col width="36%" /> |
|---|
| 210 | <col width="64%" /> |
|---|
| 211 | </colgroup> |
|---|
| 212 | <thead valign="bottom"> |
|---|
| 213 | <tr><th class="head" colspan="2">Dictionary</th> |
|---|
| 214 | </tr> |
|---|
| 215 | </thead> |
|---|
| 216 | <tbody valign="top"> |
|---|
| 217 | <tr><td><tt class="docutils literal"><span class="pre">m</span></tt></td> |
|---|
| 218 | <td><table border="1" class="first last docutils"> |
|---|
| 219 | <colgroup> |
|---|
| 220 | <col width="88%" /> |
|---|
| 221 | <col width="12%" /> |
|---|
| 222 | </colgroup> |
|---|
| 223 | <thead valign="bottom"> |
|---|
| 224 | <tr><th class="head" colspan="2">Dictionary</th> |
|---|
| 225 | </tr> |
|---|
| 226 | </thead> |
|---|
| 227 | <tbody valign="top"> |
|---|
| 228 | <tr><td><tt class="docutils literal"><span class="pre">LT_metadata</span></tt></td> |
|---|
| 229 | <td>1</td> |
|---|
| 230 | </tr> |
|---|
| 231 | <tr><td><tt class="docutils literal"><span class="pre">ut_pex</span></tt></td> |
|---|
| 232 | <td>2</td> |
|---|
| 233 | </tr> |
|---|
| 234 | </tbody> |
|---|
| 235 | </table> |
|---|
| 236 | </td> |
|---|
| 237 | </tr> |
|---|
| 238 | <tr><td><tt class="docutils literal"><span class="pre">p</span></tt></td> |
|---|
| 239 | <td>6881</td> |
|---|
| 240 | </tr> |
|---|
| 241 | <tr><td><tt class="docutils literal"><span class="pre">v</span></tt></td> |
|---|
| 242 | <td>"µTorrent 1.2"</td> |
|---|
| 243 | </tr> |
|---|
| 244 | </tbody> |
|---|
| 245 | </table> |
|---|
| 246 | <p>and in the encoded form:</p> |
|---|
| 247 | <p><tt class="docutils literal"><span class="pre">d1:md11:LT_metadatai1e6:µT_PEXi2ee1:pi6881e1:v13:\xc2\xb5Torrent</span> <span class="pre">1.2e</span></tt></p> |
|---|
| 248 | <p>To make sure the extension names do not collide by mistake, they should be |
|---|
| 249 | prefixed with the two (or one) character code that is used to identify the |
|---|
| 250 | client that introduced the extension. This applies for both the names of |
|---|
| 251 | extension messages, and for any additional information put inside the |
|---|
| 252 | top-level dictionary. All one and two byte identifiers are invalid to use |
|---|
| 253 | unless defined by this specification.</p> |
|---|
| 254 | <p>This message should be sent immediately after the standard bittorrent handshake |
|---|
| 255 | to any peer that supports this extension protocol. It is valid to send the |
|---|
| 256 | handshake message more than once during the lifetime of a connection, |
|---|
| 257 | the sending client should not be disconnected. An implementation may choose |
|---|
| 258 | to ignore the subsequent handshake messages (or parts of them).</p> |
|---|
| 259 | <p>Subsequent handshake messages can be used to enable/disable extensions |
|---|
| 260 | without restarting the connection. If a peer supports changing extensions |
|---|
| 261 | at run time, it should note that the <tt class="docutils literal"><span class="pre">m</span></tt> dictionary is additive. |
|---|
| 262 | It's enough that it contains the actual <em>CHANGES</em> to the extension list. |
|---|
| 263 | To disable the support for <tt class="docutils literal"><span class="pre">LT_metadata</span></tt> at run-time, without affecting |
|---|
| 264 | any other extensions, this message should be sent: |
|---|
| 265 | <tt class="docutils literal"><span class="pre">d11:LT_metadatai0ee</span></tt>. |
|---|
| 266 | As specified above, the value 0 is used to turn off an extension.</p> |
|---|
| 267 | <p>The extension IDs must be stored for every peer, becuase every peer may have |
|---|
| 268 | different IDs for the same extension.</p> |
|---|
| 269 | <p>This specification, deliberately, does not specify any extensions such as |
|---|
| 270 | peer-exchange or metadata exchange. This protocol is merely a transport |
|---|
| 271 | for the actual extensions to the bittorrent protocol and the extensions |
|---|
| 272 | named in the example above (such as <tt class="docutils literal"><span class="pre">p</span></tt>) are just examples of possible |
|---|
| 273 | extensions.</p> |
|---|
| 274 | </div> |
|---|
| 275 | <div class="section" id="rationale"> |
|---|
| 276 | <h1>rationale</h1> |
|---|
| 277 | <p>The reason why the extension messages' IDs would be defined in the handshake |
|---|
| 278 | is to avoid having a global registry of message IDs. Instead the names of the |
|---|
| 279 | extension messages requires unique names, which is much easier to do without |
|---|
| 280 | a global registry. The convention is to use a two letter prefix on the |
|---|
| 281 | extension message names, the prefix would identify the client first |
|---|
| 282 | implementing the extension message. e.g. <tt class="docutils literal"><span class="pre">LT_metadata</span></tt> is implemented by |
|---|
| 283 | libtorrent, and hence it has the <tt class="docutils literal"><span class="pre">LT</span></tt> prefix.</p> |
|---|
| 284 | <p>If the client supporting the extensions can decide which numbers the messages |
|---|
| 285 | it receives will have, it means they are constants within that client. i.e. |
|---|
| 286 | they can be used in <tt class="docutils literal"><span class="pre">switch</span></tt> statements. It's easy for the other end to |
|---|
| 287 | store an array with the ID's we expect for each message and use that for |
|---|
| 288 | lookups each time it sends an extension message.</p> |
|---|
| 289 | <p>The reason for having a dictionary instead of having an array (using |
|---|
| 290 | implicitly assigned index numbers to the extensions) is that if a client |
|---|
| 291 | want to disable some extensions, the ID numbers would change, and it wouldn't |
|---|
| 292 | be able to use constants (and hence, not use them in a <tt class="docutils literal"><span class="pre">switch</span></tt>). If the |
|---|
| 293 | messages IDs would map directly to bittorrent message IDs, It would also make |
|---|
| 294 | it possible to map extensions in the handshake to existing extensions with |
|---|
| 295 | fixed message IDs.</p> |
|---|
| 296 | <p>The reasoning behind having a single byte as extended message identifier is |
|---|
| 297 | to follow the the bittorrent spec. with its single byte message identifiers. |
|---|
| 298 | It is also considered to be enough. It won't limit the total number of |
|---|
| 299 | extensions, only the number of extensions used simultaneously.</p> |
|---|
| 300 | <p>The reason for using single byte identifiers for the standardized handshake |
|---|
| 301 | identifiers is 1) The mainline DHT uses single byte identifiers. 2) Saves |
|---|
| 302 | bandwidth. The only advantage of longer messages is that it makes the |
|---|
| 303 | protocol more readable for a human, but the BT protocol wasn't designed to |
|---|
| 304 | be a human readable protocol, so why bother.</p> |
|---|
| 305 | <!-- Local Variables: |
|---|
| 306 | mode: indented-text |
|---|
| 307 | indent-tabs-mode: nil |
|---|
| 308 | sentence-end-double-space: t |
|---|
| 309 | fill-column: 70 |
|---|
| 310 | coding: utf-8 |
|---|
| 311 | End: --> |
|---|
| 312 | </div> |
|---|
| 313 | |
|---|
| 314 | |
|---|
| 315 | </div> |
|---|
| 316 | <div id="footer"> |
|---|
| 317 | <hr/> |
|---|
| 318 | </div> |
|---|
| 319 | |
|---|
| 320 | </div> |
|---|
| 321 | </body> |
|---|
| 322 | </html> |
|---|
