📄 extension_protocol.html
字号:
<?xml version="1.0" encoding="utf-8" ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" /><title></title><meta name="author" content="Arvid Norberg, arvid@rasterbar.com Ludvig Strigeus, ludde@utorrent.com" /><link rel="stylesheet" href="style.css" type="text/css" /></head><body><div class="document"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Arvid Norberg, <a class="reference" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a>Ludvig Strigeus, <a class="last reference" href="mailto:ludde@utorrent.com">ludde@utorrent.com</a></td></tr></tbody></table><div class="section" id="extension-protocol-for-bittorrent"><h1><a name="extension-protocol-for-bittorrent">extension protocol for bittorrent</a></h1><p>The intention of this protocol is to provide a simple and thin transportfor extensions to the bittorrent protocol. Supporting this protocol makesit easy to add new extensions without interfering with the standardbittorrent protocol or clients that don't support this extension or theone you want to add.</p><p>To advertise to other clients that you support, one bit from the reservedbytes is used.</p><p>The bit selected for the extension protocol is bit 20 from the right (countingstarts at 0). So (reserved_byte[5] & 0x10) is the expression to use for checkingif the client supports extended messaging.</p><p>Once support for the protocol is established, the client is supposed tosupport 1 new message:</p><table border="1" class="docutils"><colgroup><col width="86%" /><col width="14%" /></colgroup><thead valign="bottom"><tr><th class="head">name</th><th class="head">id</th></tr></thead><tbody valign="top"><tr><td><tt class="docutils literal"><span class="pre">extended</span></tt></td><td>20</td></tr></tbody></table><p>This message is sent as any other bittorrent message, with a 4 byte lengthprefix and a single byte identifying the message (the single byte being 20in this case). At the start of the payload of the message, is a single bytemessage identifier. This identifier can refer to different extension messagesand only one ID is specified, 0. If the ID is 0, the message is a handshakemessage which is described below. The layout of a general <tt class="docutils literal"><span class="pre">extended</span></tt> messagefollows (including the message headers used by the bittorrent protocol):</p><table border="1" class="docutils"><colgroup><col width="15%" /><col width="85%" /></colgroup><thead valign="bottom"><tr><th class="head">size</th><th class="head">description</th></tr></thead><tbody valign="top"><tr><td>uint32_t</td><td>length prefix. Specifies the number of bytes for theentire message. (Big endian)</td></tr><tr><td>uint8_t</td><td>bittorrent message ID, = 20</td></tr><tr><td>uint8_t</td><td>extended message ID. 0 = handshake, >0 = extendedmessage as specified by the handshake.</td></tr></tbody></table><div class="section" id="handshake-message"><h2><a name="handshake-message">handshake message</a></h2><p>The payload of the handshake message is a bencoded dictionary. All itemsin the dictionary are optional. Any unknown names should be ignoredby the client. All parts of the dictionary are case sensitive.This is the defined item in the dictionary:</p><table border="1" class="docutils"><colgroup><col width="11%" /><col width="89%" /></colgroup><thead valign="bottom"><tr><th class="head">name</th><th class="head">description</th></tr></thead><tbody valign="top"><tr><td>m</td><td>Dictionary of supported extension messages which mapsnames of extensions to identification numbers of eachextension. The only requirement on the identificationnumbers is that no extensions share the same. Settingan extension number to zero means that the extension isnot supported/disabled. The client should ignore anyextension names it doesn't recognize.</td></tr></tbody></table><p>Here are two other items that an implementation may choose to support:</p><table border="1" class="docutils"><colgroup><col width="11%" /><col width="89%" /></colgroup><thead valign="bottom"><tr><th class="head">name</th><th class="head">description</th></tr></thead><tbody valign="top"><tr><td>p</td><td>Local TCP listen port. Allows each side to learn aboutthe TCP port number of the other side. Note that there isno need for the receiving side of the connection to sendthis extension message, since its port number is alreadyknown.</td></tr><tr><td>v</td><td>Client name and version (as an utf-8 string).This is a much more reliable way of identifying theclient than relying on the peer id encoding.</td></tr><tr><td>reqq</td><td>An integer, the number of outstanding request messagesthis client supports without dropping any. The default inin libtorrent is 250.</td></tr></tbody></table><p>The handshake dictionary could also include extended handshakeinformation, such as support for encrypted headers or anythingimaginable.</p><p>An example of what the payload of a handshake message could look like:</p><table border="1" class="docutils"><colgroup><col width="36%" /><col width="64%" /></colgroup><thead valign="bottom"><tr><th class="head" colspan="2">Dictionary</th></tr></thead><tbody valign="top"><tr><td><tt class="docutils literal"><span class="pre">m</span></tt></td><td><table border="1" class="first last docutils"><colgroup><col width="88%" /><col width="12%" /></colgroup><thead valign="bottom"><tr><th class="head" colspan="2">Dictionary</th></tr></thead><tbody valign="top"><tr><td><tt class="docutils literal"><span class="pre">LT_metadata</span></tt></td><td>1</td></tr><tr><td><tt class="docutils literal"><span class="pre">碌T_PEX</span></tt></td><td>2</td></tr></tbody></table></td></tr><tr><td><tt class="docutils literal"><span class="pre">p</span></tt></td><td>6881</td></tr><tr><td><tt class="docutils literal"><span class="pre">v</span></tt></td><td>"碌Torrent 1.2"</td></tr></tbody></table><p>and in the encoded form:</p><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><p>To make sure the extension names do not collide by mistake, they should beprefixed with the two (or one) character code that is used to identify theclient that introduced the extension. This applies for both the names ofextension messages, and for any additional information put inside thetop-level dictionary. All one and two byte identifiers are invalid to useunless defined by this specification.</p><p>This message should be sent immediately after the standard bittorrent handshaketo any peer that supports this extension protocol. It is valid to send thehandshake message more than once during the lifetime of a connection,the sending client should not be disconnected. An implementation may chooseto ignore the subsequent handshake messages (or parts of them).</p><p>Subsequent handshake messages can be used to enable/disable extensionswithout restarting the connection. If a peer supports changing extensionsat run time, it should note that the <tt class="docutils literal"><span class="pre">m</span></tt> dictionary is additive.It's enough that it contains the actual <em>CHANGES</em> to the extension list.To disable the support for <tt class="docutils literal"><span class="pre">LT_metadata</span></tt> at run-time, without affectingany other extensions, this message should be sent:<tt class="docutils literal"><span class="pre">d11:LT_metadatai0ee</span></tt>.As specified above, the value 0 is used to turn off an extension.</p><p>The extension IDs must be stored for every peer, becuase every peer may havedifferent IDs for the same extension.</p><p>This specification, deliberately, does not specify any extensions such aspeer-exchange or metadata exchange. This protocol is merely a transportfor the actual extensions to the bittorrent protocol and the extensionsnamed in the example above (such as <tt class="docutils literal"><span class="pre">p</span></tt>) are just examples of possibleextensions.</p></div><div class="section" id="rationale"><h2><a name="rationale">rationale</a></h2><p>The reason why the extension messages' IDs would be defined in the handshakeis to avoid having a global registry somewhere, where ID's are assignedglobal identifiers. Now the extensions have unique names.</p><p>If the client supporting the extensions can decide which numbers the messagesit receives will have, it means they are constants within that client. i.e.they can be used in <tt class="docutils literal"><span class="pre">switch</span></tt> statements. It's easy for the other end tostore an array with the ID's we expect for each message and use that forlookups each time it sends an extension message.</p><p>The reason for having a dictionary instead of having an array (usingimplicitly assigned index numbers to the extensions) is that if a clientwant to disable some extensions, the ID numbers would change, and it wouldn'tbe able to use constants (and hence, not use them in a <tt class="docutils literal"><span class="pre">switch</span></tt>). If themessages IDs would map directly to bittorrent message IDs, It would also makeit possible to map extensions in the handshake to existing extensions withfixed message IDs.</p><p>The reasoning behind having a single byte as extended message identifier isto follow the the bittorrent spec. with its single byte message identifiers.It is also considered to be enough. It won't limit the total number ofextensions, only the number of extensions used simultaneously.</p><p>The reason for using single byte identifiers for the standardized handshakeidentifiers is 1) The mainline DHT uses single byte identifiers. 2) Savesbandwidth. The only advantage of longer messages is that it makes theprotocol more readable for a human, but the BT protocol wasn't designed tobe a human readable protocol, so why bother.</p></div></div></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -