Magnet URI scheme

Magnet icon

The magnet: URI scheme is a draft open standard defining a URI scheme for magnet links, which are mainly used to reference resources available for download via peer-to-peer networks. Such a link typically identifies a file not by location or name, but by content; more precisely, by the content's cryptographic hash value.

Since it refers to a file based on content or metadata, rather than by location, a magnet link can be considered a kind of Uniform Resource Name, rather than the more common Uniform Resource Locators. Although it could be used for other applications, it is particularly useful in (but not limited to) a peer-to-peer context, because it allows resources to be referenced without the need for a continuously available host.

History

The standard was developed in 2002, partly as a "vendor- and project-neutral generalization" of the ed2k: and freenet: URI schemes used by eDonkey2000 and Freenet, respectively, and attempts to follow official IETF URI standards as closely as possible.

Applications supporting magnet links include aMule, BitComet, BitSpirit, BitTorrent, DC++, Deluge, FrostWire, gtk-gnutella, KTorrent, LimeWire, MLDonkey, Morpheus, Qbittorrent, Shareaza, Transmission, μTorrent and Vuze.

Use of content hashes

The most common use of magnet links is to link to a particular file based on a hash of its contents, producing a unique identifier for the file, similar to an ISBN or catalog number. Unlike traditional identifiers, however, content-based signatures can be generated by anyone who already has the file, and so do not need a central authority to issue them. This makes them popular for use as "guaranteed" search terms within the file sharing community where anyone can distribute a magnet link to ensure that the resource retrieved by that link is the one intended, regardless of how it is retrieved. While it is technically possible that two files could have the same hash value, the cryptographic hash functions are designed to make this statistically very unlikely.

Another advantage of magnet links is their open nature and platform independence: the same magnet link can be used to download a resource from one of any number of applications on almost any operating system. Because magnets are concise and plain-text, it is possible for users to simply copy-and-paste the links into emails or instant messages, a property not found in, for example, BitTorrent files.

Technical description

Magnet links consist of a series of one or more parameters, the order of which is not significant, formatted in the same way as the query string on the end of many HTTP URLs. The most common parameter is "xt", meaning "exact topic", which is generally a URN formed from the content hash of a particular file, e.g..

magnet:?xt=urn:sha1:YNCKHTQCWBTRNJIV4WNAE52SJUQCZO5C

referring to the Base32 encoded SHA-1 hash of the file in question. Note that although this refers to a particular file, a search must still be carried out by the client application to determine where, if anywhere, it can obtain that file.

Other parameters defined by the draft standard are:

• "dn" ("display name"): a filename to display to the user, for convenience
• "kt" ("keyword topic"): a more general search, specifying search terms rather than a particular file
• "mt" ("manifest topic"): a URI pointing to a "manifest", e.g. a list of further items
• application-specific experimental parameters, which must begin "x."

The standard also suggests that multiple parameters of the same type can be used by appending ".1", ".2" etc. to the parameter name, e.g.

magnet:?xt.1=urn:sha1:YNCKHTQCWBTRNJIV4WNAE52SJUQCZO5C&xt.2=urn:sha1:TXGCZQTH26NL6OUQAJJPFALHG2LTGBC7

Description

Magnet links can contain one or more parameters, separated from each other by '&'. The order of parameters is not documented. For some values of the parameter is important for the proper parsing of client MAGNET links.

   magnet:? xl = [Size in Bytes] & dn = [file name (URL encoded)] & xt = urn: tree: tiger: [ TTH hash (Base32) ] 

Parameters

• dn (Display Name) - Filename
• xl (eXact Length) - Size in bytes
• xt (eXact Topic) - URN containing file hash
• as (Acceptable Source) - Web link to the file online
• xs (eXact Source) - P2P link.
• kt (Keyword Topic) - Key words for search
• mt (Manifest Topic) - link to the metafile that contains a list of magneto (MAGMA - MAGnet MAnifest)
• tr (address TRacker) - Tracker URL for BitTorrent downloads

URN, containing hash (xt)

"xt" stands for "exact topic". This token is the most important part of Magnet links. It is used to find and verify files included in the Magnet link.

TTH (Tiger Tree Hash)

TigerTree hashes are used in several networks including Direct Connect and Gnutella2.

  xt=urn:tree:tiger:[ TTH Hash (Base32) ]

SHA-1 (Secure Hash Algorithm 1)

Hash sum used on gnutella and G2 (Gnutella2).

  xt=urn:sha1:[ SHA-1 Hash (Base32) ]

BitPrint

This hash code consists of an SHA-1 Hash followed by a TTH Hash delimited by a point. Hash sum used on gnutella and G2 (Gnutella2).

  xt=urn:bitprint:[ SHA-1 Hash (Base32) ].[ TTH Hash (Base32) ]

ED2K (eDonkey2000) Hash

Hash sum used on eDonkey2000.

  xt=urn:ed2k:[ ED2K Hash (Hex) ]

AICH (Advanced Intelligent Corruption Handler)

No formal URN for Magnet links. Hash sum used on eDonkey2000 to restore and control the integrity of downloaded/downloading files.

  xt=urn:aich:[ aich Hash (Base32) ]

Kazaa Hash

Hash sum used on FastTrack. Vulnerable to hash collision attacks.

  xt=urn:kzhash:[ Kazaa Hash (Hex) ]

BTIH (BitTorrent Info Hash)

Hash sum of the "info" section of a BitTorrent metafile as used by BitTorrent to identify downloadable files or sets of files.

  xt=urn:btih:[ BitTorrent Info Hash (Hex) ]

Some clients require Base32 of info_hash (Vuze for ex.).

MD5 (Message Digest 5)

Hash sum supported by Gnutella2. Vulnerable to hash collision attacks.

  xt=urn:md5:[ MD5 Hash (Hex) ]

CRC-32 (Cyclic Redundancy Check)

Not a formal URN for Magnet links. Not used in any known P2P network. Hashes are not likely to be unique, making CRC-32 a poor choice for a URN.

  xt=urn:crc32:[ CRC-32 (Base10) ]

Web links to the file

There are two types of download links that can be inserted in a Magnet link as a direct or backup source.

Normal (as)

"as" stands for "acceptable source". This type of source refers to a direct download from a web server. It is thought to be only a fall-back source in case a client is unable to locate and/or download the linked-to file in its supported P2P network(s). However, most clients treat it equal to the "xs" token when it comes to priority and ignore the timeout before contacting "as" sources specified by the specs.

  as=[ a web link to the file(URL encoded) ]

P2P (xs)

"xs" stands for "exact source". It is either an HTTP (HTTPS, FTP, FTPS, etc.) download source for the file linked to by the Magnet link, the address of a P2P source for the file or the address of a hub (in the case of DC++). For this link a client tries to connect directly and asks for the file and/or its sources. This field is commonly used P2P clients to store the source. The reference may include the file hash.

Content-Addressable Web^[1] URL

This type of link is used by gnutella as well as G2 applications and based on RFC 2168.

xs=http://[Client Address]:[Port of client]/uri-res/N2R?[ URN containing a file hash ]

Example:

xs=http://192.0.2.27:6346/uri-res/N2R?urn:sha1:FINYVGHENTHSMNDSQQYDNLPONVBZTICF

Link to a DirectConnect hub to find sources for a file

This link connects a DirectConnect client immediately to the hub in question.

  xs=dchub://[hub address]:[hub port]

Reference to a web-based source cache for a file on Gnutella2

In this case, the link included points not to a client IP or direct source, but to a source cache. Such a cache doesn't have the file itself, but it stores the IPs of other clients contacting it to download the same file. Once a client connects to the cache, it is served IPs for alternate sources, while its own IP is stored inside the cache and forwarded to the next one connecting to the cache. This system operates similar to a BitTorrent tracker.

  xs=http://cache.freebase.be/[ SHA-1 hash ]

Reference to an eD2k source

  xs=ed2kftp://[client address]:[client port]/[ed2k hash]/[file size]/

Manifest (mt)

This is a link to a list of links (see list). Perhaps as a web link...

  mt=http://weblog.foo/all-my-favorites.rss

...or an URN

  mt=urn:sha1:3I42H3S6NNFQ2MSVX7XZKYAYSCX5QBYJ

Keywords (kt)

This field specifies a string of search keywords to search for in P2P networks.

  kt=martin+luther+king+mp3

Address tracker (tr)

Tracker URL. Used to obtain resources for BitTorrent downloads without a need for DHT support.

  tr=http://example.com/announce

Supplement format (x.)

For experimental and self-complementing informal options, the prefix x followed by a chosen second letter can be used

  x.[name of the new parameter]=[data of the new parameter (URL encoded)]

Group settings

Allows to include several files and their URNs, names and hashes in the Magnet link by adding a count number preceded by a dot (".") to each link parameter.

  magnet:?xt.1=[ URN of the first file]&xt.2=[ URN of the second file]

Examples

Link to the file of zero bytes length

magnet:?xt=urn:ed2k:31D6CFE0D16AE931B73C59D7E0C089C0
&xl=0&dn=zero_len.fil
&xt=urn:bitprint:3I42H3S6NNFQ2MSVX7XZKYAYSCX5QBYJ
.LWPNACQDBZRYXW3VHJVCJ64QBZNGHOHHHZWCLNQ
&xt=urn:md5:D41D8CD98F00B204E9800998ECF8427E

mediawiki-1.15.1.tar.gz

magnet:?xt=urn:ed2k:354B15E68FB8F36D7CD88FF94116CDC1
&xl=10826029&dn=mediawiki-1.15.1.tar.gz
&xt=urn:tree:tiger:7N5OAMRNGMSSEUE3ORHOKWN4WWIQ5X4EBOOTLJY
&xt=urn:btih:QHQXPYWMACKDWKP47RRVIV7VOURXFE5Q
&tr=http%3A%2F%2Ftracker.example.org%2Fannounce.php%3Fuk%3D1111111111%26
&as=http%3A%2F%2Fdownload.wikimedia.org%2Fmediawiki%2F1.15%2Fmediawiki-1.15.1.tar.gz
&xs=http%3A%2F%2Fcache.example.org%2FXRX2PEFXOOEJFRVUCX6HMZMKS5TWG4K5
&xs=dchub://example.org

url magnet (mediawiki-1.15.1.tar.gz)

http://sure-raza.com/magnet:?xl=10826029&dn=mediawiki-1.15.1.tar.gz&xt=urn:tree:tiger:7N5OAMRNGMSSEUE3ORHOKWN4WWIQ5X4EBOOTLJY

Features

Client	dn	xl	xt	tr	xs	as	kt	mt	Interception[2]	Box[3]
AMule	Yes	Yes	urn: ed2k:	No	?	?	?	?	No	Yes
ApexDC++	Yes	Yes	Urn: tree: tiger: urn: bitprint:	No	Dchub:[4]	Dchub:[4]	No	?	Yes	No
FlylinkDC++	Yes	Yes	Urn: tree: tiger: urn: bitprint:	No	Dchub:[4]	Dchub:[4]	Yes	?	Yes	No
Azureus	?	?	urn: btih:	?	?	?	?	?	?	?
BitComet	Yes	Yes	urn: btih:	Yes	No	No	No	No	Yes	Yes
Deluge	Yes	?	urn: btih:	Yes	?	?	?	?	Yes	Yes
LimeWire	Yes	Yes	urn: sha1:	No	http: urn: guid:	?	No	No	Yes	Yes
KTorrent	Yes	No	urn: btih:	Yes	No	No	No	No	Yes	Yes
µTorrent	Yes	No	urn: btih:	Yes	No	No	No	No	Yes	Yes
Shareaza	Yes	Yes	urn: sha1: urn: tree: tiger: urn: bitprint: urn: ed2k: urn: md5: urn: btih:	Yes [5]	http: ftp:	http: ftp: (Same priority as xs)	Yes	No	Yes	Yes
Transmission[6][7]	Yes	No	urn: btih:	Yes	No	No	No	No	Yes	Yes

Shareaza

Able to intercept links from within the web browser and has a possibility to directly insert Magnet links to the client by pasting them into the search area or the "Download File or Torrent" dialogue.

aMule 2.2

Unable to intercept Magnet links from within a web browser. Supports Magnets by offering a text box at the bottom of the client where they can be copy/pasted into.

However, the client is only able to recognize eD2k hash, file size and name in this exact order and therefore, many valid links may not be suitable for downloading.

See also

• Metalink

References

1. ^ Content-Addressable Web
2. ^ Ability to intercept Magnet links directly from within the web browser. i.e. When a Magnet link is entered into the address bar, the application will intercept the link and try to open the link itself. So if a compatible client is installed on your computer and you enter a Magnet link into your browser address bar, a window pops up asking if you want to allow that client to open the link.
3. ^ Possibility to inject the link directly into the application in question.
4. ^ ^{a b c d} Dchub://[hubaddress]:[hubport]
5. ^ Since v2.5.1.0
6. ^ http://trac.transmissionbt.com/browser/trunk/libtransmission/magnet-test.c?rev=9531
7. ^ http://trac.transmissionbt.com/browser/trunk/libtransmission/magnet.c?rev=9979

External links

• MAGNET-URI Project Web-site
• Bitzi, a Magnet search engine / directory.
• Freebase a website that uses magnet links to index freeware.
• RHash, an open source command-line tool, which can calculate magnet links.