from Sebastian: 235-kill-named-flag.txt
[torspec.git] / proposals / ideas / xxx-onion-nyms.txt
1 Filename: xxx-onion-nyms.txt
2 Title: .onion nym system
3 Author: Arturo Filastò, Jacob Appelbaum
4 Created: 17 December 2011
5 Status: Draft
6
7 1. Intro and Motivation
8
9   The main issue that prohibits the wide scale adoption of .onion addressing
10   is the fact that they are not human memorable. While Zooko's triangle says that
11   you can only have at most two of "memorable", "secure" and "global" it is
12   possible to build a simple nym mechanism that relies on the current .onion
13   addressing system.  We define a basic registration system generally and also
14   it's particual application to the tor2web network. This is a very simple kind
15   of petname system for applications such as tor2web.
16
17 2. Definitions
18
19   These are the definitions of the actors involved in the process.
20
21   Beppe - The owner of the Tor Hidden Service
22   User - A random user of Tor/tor2web
23   v2cbb2l4lsnpio4q.onion - The .onion address that Beppe is interested in registering
24   antani - The nym Beppe is interested in associating to v2cbb2l4lsnpio4q.onion
25   t2w - A tor2web node
26
27
28 3. Registration
29
30   This is the process through which Beppe is able to make a registration for his chosen
31   nym.
32
33 3.1 General implementation
34
35   Beppe wishes to register "antani" to point to v2cbb2l4lsnpio4q.onion so he creates a
36   a TCP service listening on his .onion will respond with the string "reg antani" when
37   interrogated. The requester will make a lookup in his database to see if
38   "antani" is already registered. If it is not registered the "antani" <->
39   v2cbb2l4lsnpio4q.onion mapping is created. A timestamp is added to the
40   database.
41
42 3.2 Tor2web implementation
43
44   Beppe creates a file called "onion.txt" containing the string "reg antani" and uploads
45   it to the root of his web server. When User visits v2cbb2l4lsnpio4q.tor2web.org the
46   t2w checks if his database contains a mapping with v2cbb2l4lsnpio4q.onion, if it does
47   not, it requests the http://v2cbb2l4lsnpio4q.onion/onion.txt file.
48   If the file exists t2w reads it and extracts the "antani" string. A lookup is made in
49   his database. If "antani" is not registered he creates a mapping between "antani" and
50   v2cbb2l4lsnpio4q.onion. A timestamp is added to the database.
51
52 4. Expiration
53
54   A nym will expire if either the HS goes offline for longer than a given time
55   threshold or if he explicitly requests removal of the association to that
56   particualr nym. This allows dynamic reallocation of nyms and avoids nym
57   squatting.
58
59 4.1 Time delay
60
61   We define the default tiem threshold to be 30 days since the last check. At
62   the time of expiry or anytime before, another request is made to either the TCP
63   service or for the "onion.txt" file. If the Hidden Service is offline or if
64   the requested mapping has changed the mapping is removed or modified.  If the
65   onion.txt is unchanged, the nym remains valid and the database timestamp
66   entry is updated.
67
68   4.2 Release
69
70   The HS can specify the "release" string to delete the entry from the nym database.
71
72 5. Synchronization
73
74   To keep the database of registered nyms up to date in for many t2w nodes, a synchronization
75   mechanism is required but currently out of scope for this document.
76
77