Home > Specs > BitTorrent > Peer Connections
Extended Handshake
The first message transmitted after the bitfield should be the extended handshake, which indicates support for several features that were not included in the original protocol but are now considered essential for operation.
The first byte of this message is the message type, which is 20, which means this is an
extension message.
The next byte is the extension message sub-type. Zero is the sub-type of the extended handshake.
The extended handshake (sub-type 0) contains a BEncoded map.
Here is a list of common keys for the extended handshake map:
p
The value of this key is an integer that is the remote incoming connection port #. This information is useful if we receive an incoming TCP connection, so that we can re-connect to the peer later. TCP connections always come from a source port that is different than the peer's incoming connection port.
yourip
The value of this key is a string that is the compact binary representation of the receiving peer's IP address. It will be 4 bytes for IPv4 and 16 bytes for IPv6. It is not used generally.
reqq
The value of this key is an integer that specifies the maximum number of
block requests that should be pipelined when downloading from the remote peer.
upload_only
This is an integer, either 0 or 1, to indicate that the peer is in "upload only" mode, which means it has either completely downloaded the torrent, or it does not desire to download any more (partial multi-file download). This flag is somewhat obsolete, and the newer
upload_only extension message (below) should be used instead.
metadata_size
This is an integer that specifies the size of the BEncoded representation of the torrent
info.
v
This is a string with the client program name and version.
m
The value of this key is a map of integers. Each map entry represents an extended message sub-type. The key is a well-known identifier, and the value is the integer extended message sub-type that will be used for this particular connection.
Here are some common extension message identifiers:
ut_metadata
This message is used for
downloading the torrent info in chunks.
ut_pex
This stands for
Peer EXchange. This message is used to inform connected peers about the current state of your other peer connections.
i2p_pex
This is the same as ut_pex, but this message is used for I2P peer addresses.
ut_holepunch
Using this,
holepunching messages can be relayed to the PEX peers of any connected peer, which will cause them to attempt an outgoing connection to the originator of the holepunch message. This is a method for getting around NAT routers that don't allow incoming connections.
i2p_dht
This message contains a BEncoded map with two keys,
port and
rport, each with an integer value. It is used to inform the remote peer of the local peer's DHT ports. In the separate I2P DHT, two separate UDP ports are used for messages due to the nature of the I2P protocol design.
lt_donthave
This message contains a single integer value, which indicates a piece index that the remote once had but does no longer have. It is the opposite of a
HAVE message. It can be needed sometimes if the user deletes a file or a file fails a hash-check due to corruption while the torrent is running.
upload_only
This message contains a single 4-byte big-endian value, which can be zero or one. A one indicates that the peer is complete (possibly
partially) and is not interested in downloading anything.
