Home > Specs > BitTorrent
Protocol Version 3
Written by Kevin Hearn (kh@tixati.com)
Last update October 6, 2025
The improvements made in this version are to address the
problems with the SHA-1 hashing algorithm in BitTorrent.
Two keys are added to the
torrent info map. One contains complimentary piece hashes that make it much more difficult to produce two different pieces that have the same combined hash set. The other is a mild proof of work to make it more difficult to produce two different info maps with the same hash and a valid proof of work. Both keys can optionally be used with multiple algorithms.
piece_hashes
The value of this key is a map. The map's keys are hash algorithm and width specification strings. Each corresponding map value is a string that is the hash of each piece, concatenated, much like the regular
pieces hash field.
The algorithm specifiers currently in use are
SHA2-256 and
SHA3-256. When checking specifiers, do so in a case-insensitive manner.
An algorithm specifier can optionally be appended with a width specifier. It is in the form of a hyphen and then a number of bits. The number of bits must be a multiple of 8. The output of the hash function is simply truncated to the specified width.
Example specifiers:
SHA3-256
This would be a full hash, 256 bits (32 bytes) per piece.
SHA3-256-32
This is the same hash truncated to 32 bits, which is 4 bytes per piece.
When combined with the old SHA-1 piece hashes, the overall difficulty of producing a usable collision is significantly increased. Even if using only 32 bits of additional hash, it becomes very impractical to find a collision with the same SHA-1 hash and the same additional partial hash.
Client implementations will need to decide for themselves which algorithms and widths are considered secure when creating a torrent or presenting a newly loaded torrent to the user.
info_pow
The value of this key is a map. The map's keys are hash algorithm and difficulty specification strings. Each corresponding map value is a string that contains an output hash and a nonce.
The algorithm specifiers currently in use are
SHA2-256 and
SHA3-256. When checking specifiers, do so in a case-insensitive manner.
An algorithm specifier must be appended with a difficulty specifier. It is in the form of a hyphen and then a number of bits. The number of bits does not need to be a multiple of 8.
Example specifiers:
SHA3-256-18
The SHA3-256 algorithm is in use, which produces a 32 byte hash. The final output hash must start with 18 zero bits.
SHA2-256-23
The SHA2-256 algorithm is in use, which produces a 32 byte hash. The final output hash must start with 23 zero bits.
To create the hash+nonce string for a particular algorithm and difficulty key, first hash (using the specified hash algorithm) the entire info key in BEncoded format, with all hash+nonce string values in each
info_pow sub-key zeroed out (for all algorithms). Make sure these zeroed-out strings are long enough to hold a full hash and an 8-byte nonce, typically 40 bytes total.
Once we have a base hash for each algorithm (held in a temporary variable), we must hash it with a nonce that is incremented until the final output hash starts with, from the lowest bit of the first byte, at least as many zero bits as the specified difficulty.
Once we have done this for each algorithm key, each final output hash with the nonce appended is then saved as the string value of each respective key.
To validate a newly loaded torrent, we follow the same process, except that we already know the nonce. Simply calculate the base hash on the BEncoded info map, with all hash+nonce values zeroed out. Then hash the base hash with nonce appended. Check that the result matches the final output hash that is at the beginning of the algorithm key's string value. Also check that it starts with the required number of zero bits.
The client implementation will have to decide for itself what algorithms and difficulty levels it considers secure when creating a new torrent or presenting a newly loaded torrent to the user. A minimum of 20 bits of difficulty should be used to provide a decent level of security. When creating a torrent, it takes minimal processing power to find an appropriate nonce at this difficulty level, but it is enough to make it practically impossible to produce two different info maps that have the same SHA-1 info hash and also a valid proof of work.
