BEP:9
Title:Extension for Peers to Send Metadata Files
Version: cfd7cd53addbea7e87363ae1a52e2e4b397df3a9
Last-Modified:Sun Mar 26 01:05:53 2017 +0100
Author: Greg Hazel <greg@bittorrent.com>, Arvid Norberg <arvid@bittorrent.com>
Status: Accepted
Type:Standards Track
Created:31-Jan-2008
Post-History:14-Oct-2012: point out that unrecognized message types should be ignored 16-May-2016: added peer source parameter to magnets

The purpose of this extension is to allow clients to join a swarm and complete a download without the need of downloading a .torrent file first. This extension instead allows clients to download the metadata from peers. It makes it possible to support magnet links, a link on a web page only containing enough information to join the swarm (the info hash).

metadata

This extension only transfers the info-dictionary part of the .torrent file. This part can be validated by the info-hash. In this document, that part of the .torrent file is referred to as the metadata.

The metadata is handled in blocks of 16KiB (16384 Bytes). The metadata blocks are indexed starting at 0. All blocks are 16KiB except the last block which may be smaller.

extension header

The metadata extension uses the extension protocol (specified in BEP 0010 ) to advertize its existence. It adds the "ut_metadata" entry to the "m" dictionary in the extension header hand-shake message. This identifies the message code used for this message. It also adds "metadata_size" to the handshake message (not the "m" dictionary) specifying an integer value of the number of bytes of the metadata.

Example extension handshake message:

{'m': {'ut_metadata', 3}, 'metadata_size': 31235}

extension message

The extension messages are bencoded. There are 3 different kinds of messages:

  1. request
  2. data
  3. reject

The bencoded messages have a key "msg_type" which value is an integer corresponding to the type of message. They also have a key "piece", which indicates which part of the metadata this message refers to.

In order to support future extensability, an unrecognized message ID MUST be ignored.

request

The request message does not have any additional keys in the dictionary. The response to this message, from a peer supporting the extension, is either a reject or a data message. The response MUST have the same piece as the request did.

A peer MUST verify that any piece it sends passes the info-hash verification. i.e. until the peer has the entire metadata, it cannot run SHA-1 to verify that it yields the same hash as the info-hash. Peers that do not have the entire metadata MUST respond with a reject message to any metadata request.

Example:

{'msg_type': 0, 'piece': 0}
d8:msg_typei0e5:piecei0ee

That request message requests the first metadata piece.

data

The data message adds another entry to the dictionary, "total_size". This key has the same semantics as the "metadata_size" in the extension header. This is an integer.

The metadata piece is appended to the bencoded dictionary, it is not a part of the dictionary, but it is a part of the message (the length prefix MUST include it).

If the piece is the last piece of the metadata, it may be less than 16kiB. If it is not the last piece of the metadata, it MUST be 16kiB.

Example:

{'msg_type': 1, 'piece': 0, 'total_size': 3425}
d8:msg_typei1e5:piecei0e10:total_sizei34256eexxxxxxxx...

The x represents binary data (the metadata).

reject

The reject message does not have any additional keys in its message. It SHOULD be interpreted as the peer does not have the piece of metadata that was requested.

Clients MAY implement flood protection by rejecting request messages after a certain number of them have been served. Typically the number of pieces of metadata times a factor.

Example:

{'msg_type': 2, 'piece': 0}
d8:msg_typei1e5:piecei0ee

magnet URI format

The magnet URI format is:

v1: magnet:?xt=urn:btih:<info-hash>&dn=<name>&tr=<tracker-url>&x.pe=<peer-address>
v2: magnet:?xt=urn:btmh:<tagged-info-hash>&dn=<name>&tr=<tracker-url>&x.pe=<peer-address>
<info-hash>
Is the info-hash hex encoded, for a total of 40 characters. For compatability with existing links in the wild, clients should also support the 32 character base32 encoded info-hash.
<tagged-info-hash>
Is the multihash formatted, hex encoded full infohash for torrents in the new metadata format. 'btmh' and 'btih' exact topics may exist in the same magnet if they describe the same hybrid torrent.
<peer-address>
A peer address expressed as hostname:port, ipv4-literal:port or [ipv6-literal]:port. This parameter can be included to initiate a direct metadata transfer between two clients while reducing the need for external peer sources. It should only be included if the client can discover its public IP address and determine its reachability. Note: Since no URI scheme identifier has been allocated for bittorrent xs= is not used for this purpose.

xt is the only mandatory parameter. dn is the display name that may be used by the client to display while waiting for metadata. tr is a tracker url, if there is one. If there are multiple trackers, multiple tr entries may be included. The same applies for x.pe entries.

dn, tr and x.pe are all optional.

If no tracker is specified, the client SHOULD use the DHT (BEP 0005) to acquire peers.

References