root/dotorg/trunk/html/beps/bep_0010.html

Revision 11071, 13.3 KB (checked in by dave, 19 months ago)

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