docs/extension_protocol.rst

   1 :Author: Arvid Norberg, arvid@rasterbar.com
   2          Ludvig Strigeus, ludde@utorrent.com
   3
   4 extension protocol for bittorrent
   5 =================================
   6
   7 The intention of this protocol is to provide a simple and thin transport
   8 for extensions to the bittorrent protocol. Supporting this protocol makes
   9 it easy to add new extensions without interfering with the standard
  10 bittorrent protocol or clients that don't support this extension or the
  11 one you want to add.
  12
  13 To advertise to other clients that you support, one bit from the reserved
  14 bytes is used.
  15
  16 The bit selected for the extension protocol is bit 20 from the right (counting
  17 starts at 0). So (reserved_byte[5] & 0x10) is the expression to use for checking
  18 if the client supports extended messaging.
  19
  20 Once support for the protocol is established, the client is supposed to
  21 support 1 new message:
  22
  23 +------------------------+----+
  24 |name                    | id |
  25 +========================+====+
  26 |``extended``            | 20 |
  27 +------------------------+----+
  28
  29 This message is sent as any other bittorrent message, with a 4 byte length
  30 prefix and a single byte identifying the message (the single byte being 20
  31 in this case). At the start of the payload of the message, is a single byte
  32 message identifier. This identifier can refer to different extension messages
  33 and only one ID is specified, 0. If the ID is 0, the message is a handshake
  34 message which is described below. The layout of a general ``extended`` message
  35 follows (including the message headers used by the bittorrent protocol):
  36
  37 +----------+---------------------------------------------------------+
  38 | size     | description                                             |
  39 +==========+=========================================================+
  40 | uint32_t | length prefix. Specifies the number of bytes for the    |
  41 |          | entire message. (Big endian)                            |
  42 +----------+---------------------------------------------------------+
  43 | uint8_t  | bittorrent message ID, = 20                             |
  44 +----------+---------------------------------------------------------+
  45 | uint8_t  | extended message ID. 0 = handshake, >0 = extended       |
  46 |          | message as specified by the handshake.                  |
  47 +----------+---------------------------------------------------------+
  48
  49
  50 handshake message
  51 -----------------
  52
  53 The payload of the handshake message is a bencoded dictionary. All items
  54 in the dictionary are optional. Any unknown names should be ignored
  55 by the client. All parts of the dictionary are case sensitive.
  56 This is the defined item in the dictionary:
  57
  58 +-------+-----------------------------------------------------------+
  59 | name  | description                                               |
  60 +=======+===========================================================+
  61 | m     | Dictionary of supported extension messages which maps     |
  62 |       | names of extensions to an extended message ID for each    |
  63 |       | extension message. The only requirement on these IDs      |
  64 |       | is that no extension message share the same one. Setting  |
  65 |       | an extension number to zero means that the extension is   |
  66 |       | not supported/disabled. The client should ignore any      |
  67 |       | extension names it doesn't recognize.                     |
  68 |       |                                                           |
  69 |       | The extension message IDs are the IDs used to send the    |
  70 |       | extension messages to the peer sending this handshake.    |
  71 |       | i.e. The IDs are local to this particular peer.           |
  72 +-------+-----------------------------------------------------------+
  73
  74
  75 Here are some other items that an implementation may choose to support:
  76
  77 +-------+-----------------------------------------------------------+
  78 | name  | description                                               |
  79 +=======+===========================================================+
  80 | p     | Local TCP listen port. Allows each side to learn about    |
  81 |       | the TCP port number of the other side. Note that there is |
  82 |       | no need for the receiving side of the connection to send  |
  83 |       | this extension message, since its port number is already  |
  84 |       | known.                                                    |
  85 +-------+-----------------------------------------------------------+
  86 | v     | Client name and version (as an utf-8 string).             |
  87 |       | This is a much more reliable way of identifying the       |
  88 |       | client than relying on the peer id encoding.              |
  89 +-------+-----------------------------------------------------------+
  90 | reqq  | An integer, the number of outstanding request messages    |
  91 |       | this client supports without dropping any. The default in |
  92 |       | in libtorrent is 250.                                     |
  93 +-------+-----------------------------------------------------------+
  94
  95 The handshake dictionary could also include extended handshake
  96 information, such as support for encrypted headers or anything
  97 imaginable.
  98
  99 An example of what the payload of a handshake message could look like:
 100
 101 +------------------------------------------------------+
 102 | Dictionary                                           |
 103 +===================+==================================+
 104 | ``m``             |  +--------------------------+    |
 105 |                   |  | Dictionary               |    |
 106 |                   |  +======================+===+    |
 107 |                   |  | ``LT_metadata``      | 1 |    |
 108 |                   |  +----------------------+---+    |
 109 |                   |  | ``ut_pex``           | 2 |    |
 110 |                   |  +----------------------+---+    |
 111 |                   |                                  |
 112 +-------------------+----------------------------------+
 113 | ``p``             | 6881                             |
 114 +-------------------+----------------------------------+
 115 | ``v``             | "µTorrent 1.2"                   |
 116 +-------------------+----------------------------------+
 117
 118 and in the encoded form:
 119
 120 ``d1:md11:LT_metadatai1e6:µT_PEXi2ee1:pi6881e1:v13:\xc2\xb5Torrent 1.2e``
 121
 122 To make sure the extension names do not collide by mistake, they should be
 123 prefixed with the two (or one) character code that is used to identify the
 124 client that introduced the extension. This applies for both the names of
 125 extension messages, and for any additional information put inside the
 126 top-level dictionary. All one and two byte identifiers are invalid to use
 127 unless defined by this specification.
 128
 129 This message should be sent immediately after the standard bittorrent handshake
 130 to any peer that supports this extension protocol. It is valid to send the
 131 handshake message more than once during the lifetime of a connection,
 132 the sending client should not be disconnected. An implementation may choose
 133 to ignore the subsequent handshake messages (or parts of them).
 134
 135 Subsequent handshake messages can be used to enable/disable extensions
 136 without restarting the connection. If a peer supports changing extensions
 137 at run time, it should note that the ``m`` dictionary is additive.
 138 It's enough that it contains the actual *CHANGES* to the extension list.
 139 To disable the support for ``LT_metadata`` at run-time, without affecting
 140 any other extensions, this message should be sent:
 141 ``d11:LT_metadatai0ee``.
 142 As specified above, the value 0 is used to turn off an extension.
 143
 144 The extension IDs must be stored for every peer, becuase every peer may have
 145 different IDs for the same extension.
 146
 147 This specification, deliberately, does not specify any extensions such as
 148 peer-exchange or metadata exchange. This protocol is merely a transport
 149 for the actual extensions to the bittorrent protocol and the extensions
 150 named in the example above (such as ``p``) are just examples of possible
 151 extensions.
 152
 153 rationale
 154 ---------
 155
 156 The reason why the extension messages' IDs would be defined in the handshake
 157 is to avoid having a global registry of message IDs. Instead the names of the
 158 extension messages requires unique names, which is much easier to do without
 159 a global registry. The convention is to use a two letter prefix on the
 160 extension message names, the prefix would identify the client first
 161 implementing the extension message. e.g. ``LT_metadata`` is implemented by
 162 libtorrent, and hence it has the ``LT`` prefix.
 163
 164 If the client supporting the extensions can decide which numbers the messages
 165 it receives will have, it means they are constants within that client. i.e.
 166 they can be used in ``switch`` statements. It's easy for the other end to
 167 store an array with the ID's we expect for each message and use that for
 168 lookups each time it sends an extension message.
 169
 170 The reason for having a dictionary instead of having an array (using
 171 implicitly assigned index numbers to the extensions) is that if a client
 172 want to disable some extensions, the ID numbers would change, and it wouldn't
 173 be able to use constants (and hence, not use them in a ``switch``). If the
 174 messages IDs would map directly to bittorrent message IDs, It would also make
 175 it possible to map extensions in the handshake to existing extensions with
 176 fixed message IDs.
 177
 178 The reasoning behind having a single byte as extended message identifier is
 179 to follow the the bittorrent spec. with its single byte message identifiers.
 180 It is also considered to be enough. It won't limit the total number of
 181 extensions, only the number of extensions used simultaneously.
 182
 183 The reason for using single byte identifiers for the standardized handshake
 184 identifiers is 1) The mainline DHT uses single byte identifiers. 2) Saves
 185 bandwidth. The only advantage of longer messages is that it makes the
 186 protocol more readable for a human, but the BT protocol wasn't designed to
 187 be a human readable protocol, so why bother.
 188