diff --git a/Makefile.am b/Makefile.am index a90ad1519..fdce8d281 100644 --- a/Makefile.am +++ b/Makefile.am @@ -30,6 +30,7 @@ DOCS_IMAGES = \ docs/firetorrent.png \ docs/flush.jpg \ docs/halite_thumb.png \ + docs/hacking.html \ docs/im_thumb.jpg \ docs/leechcraft.png \ docs/libtorrent_screen.png \ diff --git a/docs/auth.rst b/docs/auth.rst deleted file mode 100644 index 4049cec2a..000000000 --- a/docs/auth.rst +++ /dev/null @@ -1,192 +0,0 @@ -=================================== -BitTorrent authentication extension -=================================== - -:Author: Arvid Norberg, arvid@rasterbar.com -:Version: 1.0.0 - -.. contents:: Table of contents - :depth: 2 - :backlinks: none - -BitTorrent authentication extension ------------------------------------ - -This extension indends to cover any combination of the following use cases: - -1. Verifying that a torrent is published by a trusted source -2. Have a swarm be private and having peers authenticate peers they connect to -3. Allow peers, with prior knowledge about each other's public key, authenticate in order to set up trusted connections to known peers (i.e. "friends") - -These building blocks could be used for building a web of trust, private -swarms and trusted sources for content. - -torrent file extension ----------------------- - -A .torrent file may have the following new fields (not inside the info-hash): - -"publisher" - containing the RSA public key of the publisher of the torrent. Private counterpart - of this key that has the authority to allow new peers onto the swarm. - -"signature" - The RSA signature of the ``info`` dictionary (specifically, the encrypted SHA-1 - hash of the ``info`` dictionary). - -These fields serve the purpose of satisfying use case (1), allowing downloaders to -verify that the torrent has a trusted source. - -extension handshake -------------------- - -In order to satisfy use case (2), any peer supporting this extension MUST verify -that each peer on the swarm it connects to and receive an incoming connection from -is authenticated by the publisher's public key, if the torrent is *private*. - -A torrent is private if the ``info`` dictionary contains an integer key ``private`` -set to 1. - -The extension handshake dictionary ("m") SHOULD contain a new extension key "lt_auth". - -For private torrents, the extension handshake dictionary -MUST contain the certificate granting this peer access to the torrent. The -certificate is a dictionary ``cert`` containing the ``info-hash``, -``pubkey`` (the peer's public key), ``expiry`` (posix time of when cert expires). -The ``cert`` dictionary MAY be extended with more fields. - -Next to the ``cert`` entry is a string ``sig`` being the signature -of the SHA-1 hash of the bencoded representation of the ``cert`` dictionary. -The signature is required for private torrents, but not required for non-private -torrents. - -An example extension handshake for a private torrent could look like this:: - - { - "cert": { - "expiry": 1333242356, - "info-hash": f0fb0ed2d73a28aece3a9e4f91c91cf60e0ea0a6, - "pubkey": - 79eaeecbfc91b129c34880e3113fc9545e7169fed95a7950a335cfcef3dd2989c - c80c69d9e66206cdb4e41eeae8b19234804cd55b3eb6dbee15a5362e3fa6eb33b - a61297dfc63426832623efdf54816474189ddf1baad1d08cb614ed130f9744671 - a0c9bdf32747c284955ad9ae65db875f4f74f51e624710fe7c3db5ec8ce55f175 - b49131cace810d6a61a9fcd0fa4e41e466e09c2a18629f4bebb8dbf4746648122 - bfc8153e3e76ea16cae62e0e1608effa6bf2f1d1954d2e3ef2ca1db327f75a1aa - 711ccad6a564821824a2708c20a9184a221554d1228fdaee39ba3ce4134847fab - 91514d4ed720fabe8082e342dfce15ced93545bdc6 - }, - "m": { - "lt_auth": 8 - } - "sig": - 1767303857272cc9133253614712584a3c6be5f81cd777e9e6e99fbf23be27ca9 - d96c3ad596521f90dd4fb2291d6c9a6108625cf58ca836c3e7f15595306cd9311 - 5c4736276cb4ee08b7f85a5eb26759bfb46b28f36cecfd73e71fac5cad8f22bb6 - 32d07ab4e530587d4fc4d21ae1c52aacbefa0a0dbabb9e24d6c552aaa464a8b94 - 97cc776e3b1b4051dbc9ef26952ab0e74188cbf1ea54f37309ef781d37b59ded7 - e6ce09a9531cc9916ecbe1fb93369da47ab79457e9709576f737e3d89e3774731 - d97ac8b1283dc46a382e4ddd5a155b17d6ded6683f508f111c5e974098315c509 - 77d533ddb52f42fa5019342496a217483b622c3a - } - - -This certificate would expire at ``Sat Mar 31 18:05:56 PDT 2012``. The values of ``sig``, -``info-hash`` and ``pubkey`` are binary strings, they are printed as hex in this example. -The RSA key size SHOULD be 2048 bits (256 bytes). - -Whenconnecting to a peer, or accepting an incoming connection, for a private torrent, -the client MUST verify the validity of the incoming certificate. This is done by: - -1. Verifying that the certificate has not expired. -2. Verifying that the ``info-hash`` matches the torrent the peers are connected over -3. Verifying that the signature ``sig``, is a valid signature made by the private counterpart of the public key of the publisher of the torrent (i.e. the ``publisher`` key in the torrent file) - -If the certificate fails any one of those checks, the peer MUST be -disconnected without exchanging any more information. As an exception, before -disconnecting, the peer MAY send an ``lt_auto`` message saying the authentication -failed. - -An example extension handshake for a non-private torrent could look like this:: - - { - "cert": { - "pubkey": - 79eaeecbfc91b129c34880e3113fc9545e7169fed95a7950a335cfcef3dd2989c - c80c69d9e66206cdb4e41eeae8b19234804cd55b3eb6dbee15a5362e3fa6eb33b - a61297dfc63426832623efdf54816474189ddf1baad1d08cb614ed130f9744671 - a0c9bdf32747c284955ad9ae65db875f4f74f51e624710fe7c3db5ec8ce55f175 - b49131cace810d6a61a9fcd0fa4e41e466e09c2a18629f4bebb8dbf4746648122 - bfc8153e3e76ea16cae62e0e1608effa6bf2f1d1954d2e3ef2ca1db327f75a1aa - 711ccad6a564821824a2708c20a9184a221554d1228fdaee39ba3ce4134847fab - 91514d4ed720fabe8082e342dfce15ced93545bdc6 - }, - "m": { - "lt_auth": 8 - } - } - -Note that the only required field in the ``cert`` in this case is the ``pubkey``, -The assumption in this case is that the public key is recognized by the client -matched by a local directory of trusted peers. This is to support use case (3). - -extension message ------------------ - -The ``lt_auth`` extension message is used to protect against man-in-the-middle attacks, -and peers trying to assume someone else's identity. To do this, the entire connection -is encrypted with RC4 following this message. If the connection is already encrypted -with RC4, this overrides that encryption by resetting the encryption state. - -It has the following format: - - ============= ============= ====================================================== - size name description - ============= ============= ====================================================== - uint8_t type 0 = encrypt the connection with RC4 using the symmetric - key passed in this message. - 1 = signature verification failed - 2 = info-hash verification failed - 3 = certificate expired - ------------- ------------- ------------------------------------------------------ - uint8_t[256] rc4_key If type is not 0, this field is not included. - The symmetric key the sender of this message will use - to encrypt every message following this one. The key - is encrypted with the recipient's public key. The - length of this field may vary, but for 2048 RSA keys - it ends up being 256 bytes. - ============= ============= ====================================================== - -Note that this message is somewhat of a layer violation, since it reaches down and -starts encrypting the entire stream below itself. This is illustrated in the figure -below. - -:: - - +---------------------------+ - | BitTorrent messages | -----+ lt_auth reaches down - +---------------------------+ | to the layer below - | (RC4 protocol encryption) | <----+ - +-------------+-------------+ - | TCP | uTP | - +----------+--+-----+-------+ - -applications ------------- - -This is a low level building block and not a complete system for authenticated or -private swarms. It does allow for peers to verify that a torrent comes from a -trusted source (assuming their public key is known in advance). It also allows -for publishers to limit access to content. - -For privacy reasons, it is possible to apply this extension in a way that each peer -uses separate identities (key pairs) for every torrent it participates in. - -Issues not covered by this extension are: - -1. How the distribution of signed certificates are distributed to peers from - the signing authority (publisher), for use case (2). -2. How peers discover each other and and *pair* by recognizing each other's - public keys for future trusted connections, for use case (3). -3. How peers learn about the public keys of trusted publishers, for use case (1). - diff --git a/docs/makefile b/docs/makefile index 1a94b0834..46283a39f 100644 --- a/docs/makefile +++ b/docs/makefile @@ -6,7 +6,6 @@ TARGETS = index \ udp_tracker_protocol \ dht_rss \ dht_store \ - auth \ client_test \ manual \ building \