Using BitTorrent Magnet Links with Firefox and Chrome

BitTorrent and Magnet Links

BitTorrent is a peer-to-peer file sharing protocol that has become the preferred method for distributing Linux ISO images and other large data sets. Estimates suggest that BitTorrent was responsible for 35% of all Internet traffic in November 2004, and, depending on geographic location, from 43% to 70% of regional traffic by February 2009.

There is quite a bit of BitTorrent-specific terminology, see the list on Wikipedia for a glossary. A key concept is the torrent metadata file which describes the torrent itself. This file is a few tens of kilobytes in size, and describes the torrent and how to find it. It begins with viewable ASCII or UTF-8 text, and then switches to non-ASCII. Here is an example:

$ hexdump -C ubuntu-12.10-desktop-amd64.iso.8149211.TPB.torrent
00000000  64 38 3a 61 6e 6e 6f 75  6e 63 65 32 39 3a 75 64  |d8:announce29:ud|
00000010  70 3a 2f 2f 74 72 61 63  6b 65 72 2e 70 75 62 6c  |p://tracker.publ|
00000020  69 63 62 74 2e 63 6f 6d  3a 38 30 31 33 3a 61 6e  |icbt.com:8013:an|
00000030  6e 6f 75 6e 63 65 2d 6c  69 73 74 6c 6c 32 39 3a  |nounce-listll29:|
00000040  75 64 70 3a 2f 2f 74 72  61 63 6b 65 72 2e 70 75  |udp://tracker.pu|
00000050  62 6c 69 63 62 74 2e 63  6f 6d 3a 38 30 65 6c 32  |blicbt.com:80el2|
00000060  33 3a 75 64 70 3a 2f 2f  74 72 61 63 6b 65 72 2e  |3:udp://tracker.|
00000070  63 63 63 2e 64 65 3a 38  30 65 6c 33 35 3a 75 64  |ccc.de:80el35:ud|
00000080  70 3a 2f 2f 74 72 61 63  6b 65 72 2e 6f 70 65 6e  |p://tracker.open|
00000090  62 69 74 74 6f 72 72 65  6e 74 2e 63 6f 6d 3a 38  |bittorrent.com:8|
000000a0  30 65 6c 34 30 3a 68 74  74 70 3a 2f 2f 74 72 61  |0el40:http://tra|
000000b0  63 6b 65 72 2e 74 68 65  70 69 72 61 74 65 62 61  |cker.thepirateba|
000000c0  79 2e 6f 72 67 2f 61 6e  6e 6f 75 6e 63 65 65 65  |y.org/announceee|
000000d0  37 3a 63 6f 6d 6d 65 6e  74 34 36 3a 54 6f 72 72  |7:comment46:Torr|
000000e0  65 6e 74 20 64 6f 77 6e  6c 6f 61 64 65 64 20 66  |ent downloaded f|
000000f0  72 6f 6d 20 68 74 74 70  3a 2f 2f 74 68 65 70 69  |rom http://thepi|
00000100  72 61 74 65 62 61 79 2e  73 65 31 30 3a 63 72 65  |ratebay.se10:cre|
00000110  61 74 65 64 20 62 79 31  35 3a 42 69 74 54 6f 72  |ated by15:BitTor|
00000120  72 65 6e 74 2f 37 38 30  30 31 33 3a 63 72 65 61  |rent/780013:crea|
00000130  74 69 6f 6e 20 64 61 74  65 69 31 33 36 30 39 38  |tion datei136098|
00000140  30 34 30 37 65 38 3a 65  6e 63 6f 64 69 6e 67 35  |0407e8:encoding5|
00000150  3a 55 54 46 2d 38 34 3a  69 6e 66 6f 64 36 3a 6c  |:UTF-84:infod6:l|
00000160  65 6e 67 74 68 69 35 32  32 32 37 36 39 36 33 65  |engthi522276963e|
00000170  34 3a 6e 61 6d 65 33 30  3a 75 62 75 6e 74 75 2d  |4:name30:ubuntu-|
00000180  31 32 2e 31 30 2d 64 65  73 6b 74 6f 70 2d 61 6d  |12.10-desktop-am|
00000190  64 36 34 2e 69 73 6f 31  32 3a 70 69 65 63 65 20  |d64.iso12:piece |
000001a0  6c 65 6e 67 74 68 69 35  32 34 32 38 38 65 36 3a  |lengthi524288e6:|
000001b0  70 69 65 63 65 73 31 39  39 34 30 3a b6 a2 31 59  |pieces19940:..1Y|
000001c0  c9 a4 46 5d 4e b9 06 f0  9c 50 ae 03 f5 bf 45 bf  |..F]N....P....E.|
000001d0  71 8c 93 d8 fc d9 b0 98  ae 4f a1 69 e9 c5 11 a7  |q........O.i....|
000001e0  85 55 05 27 9c 73 0b a6  23 c1 f2 d8 7b bd 3b 9d  |.U.'.s..#...{.;.|
000001f0  10 da 8f 55 4c 39 0a a2  63 01 84 49 cf 39 54 b5  |...UL9..c..I.9T.|
00000200  c9 48 a5 d2 56 05 3a ff  4d b4 f2 c1 ff c9 27 ea  |.H..V.:.M.....'.|
00000210  98 08 72 ae ba 0f 36 bc  0f 64 41 e8 91 2e 48 65  |..r...6..dA...He|
[... many lines omitted ...]
00004f20  c0 d1 a6 72 db ae 7a 9b  41 3c c6 4a 92 1a 5d d1  |...r..z.A<.J..].|
00004f30  d8 e0 db 59 63 3e b0 b9  ee 64 52 20 14 a1 d1 81  |...Yc>...dR ....|
00004f40  69 1d 6d cb cf 78 fe 19  1a 91 06 15 7a 79 96 80  |i.m..x......zy..|
00004f50  59 aa 37 f7 74 65 6d bb  ef 84 cf a3 3d a1 1c 91  |Y.7.tem.....=...|
00004f60  76 0f 49 a4 87 8d 45 24  60 29 df 04 11 bd 26 9b  |v.I...E$`)....&.|
00004f70  cf 60 d3 fd cc f0 75 2b  0b 8a 72 bd 4f 2c c8 97  |.`....u+..r.O,..|
00004f80  cb d1 d7 26 2e 09 0e 29  13 ff 04 3c 01 39 92 0f  |...&...)...<.9..|
00004f90  e7 49 19 1a 15 dd 62 ca  72 63 29 2c bf f5 91 9e  |.I....b.rc),....|
00004fa0  65 65                                             |ee

Do keep in mind that while BitTorrent is an efficient method for obtaining data, there is no guarantee that it is the data that you were looking for! If you are planning to install the operating system supposedly contained in the ISO image, verify the cryptographic hash of resulting download against the result from a trusted source.

A cryptographic hash is the result of a mathematical calculation on any piece of data. There are several hash functions available, MD5 is rather old and SHA-1 is a minimally acceptable one for security purposes. The output of a hash is a string of bits of fixed length, 160 bits for SHA-1, and is almost always represented in base 16 or hexadecimal. The hash value will look something like this: 7ad57cadae955bd04019389d4b9c1dcb. See my page about cryptographic hash functions for far more.

Amazon
ASIN: B007EECBCK

Amazon
ASIN: 076459981X

A torrent file like the above specifies its torrent tracker, a URL your BitTorrent client can use to find other peers currently holding needed pieces of the file. Other peers can also discover the pieces that you already have and which they need.

Of course, if other peers can do that, so can agents of the entertainment industry. So, magnet links were devised. They describe a file by its content, not its location. Put another way, a magnet link does not tell you where to find a file, but how to tell if it's the file you're looking for, based on its cryptographic hash.

A side effect of switching from torrent files to magnet links is a drastic reduction in the size of a site like The Pirate Bay. Typical torrent files are a few tens of thousands of bytes, while a typical magnet link is about 250 bytes.

Unlike torrent files, magnet links are not only small but they are also plaintext, meaning that they can be included in e-mail messages.

Below is an example magnet link. Notice that this is one very long line.

magnet:?xt=urn:btih:be3a502bb8e06d538ed51024f4e0b125942420d2&dn=ubuntu-12.10-desktop-amd64.iso&tr=udp%3A%2F%2Ftracker.openbittorrent.com%3A80&tr=udp%3A%2F%2Ftracker.publicbt.com%3A80&tr=udp%3A%2F%2Ftracker.istole.it%3A6969&tr=udp%3A%2F%2Ftracker.ccc.de%3A80

The first block is the most important as it specifies exactly what we're looking for:
urn:btih:be3a502bb8e06d538ed51024f4e0b125942420d2
The btih or BitTorrent Info Hash is the SHA1 hash encoded in base 16. We're looking for a file with SHA1 hash of 0xbe3a502bb8e06d538ed51024f4e0b125942420d2. Some BitTorrent clients use other hash values.

sha1 means a Base32 encoded SHA1 hash.
tth means a Tiger Tree Hash.
bitprint means a SHA1 hash, a period, and a TTH hash.
ed2k is used by eDonkey2000.

The dn field is the "display name" that the client will show to the user. What is the thing being downloaded?

The tr fields are the address trackers. A distributed hash table could be used instead of trackers. Notice that the : and / characters are represented by ASCII codes %3A and %2F respectively, so the above magnet file specifies these four tracker URLs:

udp://tracker.openbittorrent.com:80
udp://tracker.publicbt.com:80
udp://tracker.istole.it:6969
udp://tracker.ccc.de:80

Let's say you search for Ubuntu at The Pirate Bay. Here is an example of the first few matches.

Notice that the first two have both small red and white magnet icons and green arrows pointing down. These have both magnet links and torrent files. However, torrent files are on the way out at The Pirate Bay and other torrent indexing sites!

Most of the indexed torrents will be like the third and fourth in the list, with nothing but magnet links.

Finding torrent files and magnet links at The Pirate Bay.

We have clicked on the first one in the list. Of course, the big green "Download" buttons do nothing of the sort, they just unleash pop-up ads. But notice the two smaller green pieces of text.

The one with the magnet icon saying "Get This Torrent" will take you to the magnet link.

The rapidly disappearing link "Get Torrent File" with the green download double arrow would get you the torrent file.

Most indexed torrents are like this one, the third in the search list. Notice that it offers nothing but a magnet link.

The note below the magnet file link says that you can fix the problem with magnet links by upgrading your torrent client. That's just a come-on that tries to get you to download a Windows executable file with a claim that it installs a replacement browser. A hex dump of that executable shows that it meddles with the Windows registry.

$ hexdump -C TorchSetup.exe | \
	awk '{print $1,$NF}'
[....]
00007f10  |..0.SHGetSpecial|
00007f20  |FolderLocation..|
00007f30  |SHELL32.dll.>.Re|
00007f40  |gDeleteKeyW.*.Re|
00007f50  |gCloseKey.J.RegE|
00007f60  |numKeyW.[.RegOpe|
00007f70  |nKeyExW.L.RegEnu|
00007f80  |mValueW.h.RegQue|
00007f90  |ryValueExW..x.Re|
00007fa0  |gSetValueExW..3.|
00007fb0  |RegCreateKeyExW.|
00007fc0  |B.RegDeleteValue|
00007fd0  |W.ADVAPI32.dll..|
00007fe0  |T.ImageList_Dest|
00007ff0  |roy.O.ImageList_|
00008000  |AddMasked.S.Imag|
00008010  |eList_Create..CO|
[....]

You could convert the magnet link to a torrent file with a site like magnet2torrent.com or, possibly, magnet2torrent.me.

How Can I Use Magnet Links with Firefox and Chrome?

If you simply click on the magnet link with Firefox or Chrome, you get an error. Firefox says:

The address wasn't understood.

Firefox doesn't know how to open this address, because the protocol (magnet) isn't associated with any program.

· You might need to install other software to open this address.

First, decide which BitTorrent client tool you plan to use. I prefer KTorrent, although rtorrent can be very useful as it only requires a command-line interface.

Linux:$ which ktorrent
/usr/bin/ktorrent

OpenBSD:$ which ktorrent
/usr/local/bin/ktorrent

Get your BitTorrent client installed, and find the full path to its location. Expect something like what we see here, in either /usr/bin or /usr/local/bin.

Make sure you have the gconftool-2 program installed. If not, it's in the Gconf2 package on typical Linux distributions, and in the gconf2 package on OpenBSD.

Now, run these three commands as your ordinary user account, changing /usr/bin/ktorrent as appropriate to suit your preference as to the client and its full path. Do this as your ordinary user account and not as root:

$ gconftool-2 -t string -s /desktop/gnome/url-handlers/magnet/command "/usr/bin/ktorrent %s"
$ gconftool-2 -s /desktop/gnome/url-handlers/magnet/needs_terminal false -t bool
$ gconftool-2 -t bool -s /desktop/gnome/url-handlers/magnet/enabled true

Close your browser, restart it, and now magnet links should be understood!