README.markdown

   1 Shallot
   2 =======
   3
   4 About
   5 -----
   6 Shallot allows you to create customized .onion addresses for [Tor's][tor]
   7 [hidden services][hs].
   8
   9 By customized, it is meant that part of the address can be selected. Choosing an
  10 entire address would take far longer than the universe is believed to have been
  11 in existence.
  12
  13 Installation
  14 ------------
  15         $ ./configure && make
  16         $ ./shallot
  17
  18 Usage
  19 -----
  20         $ ./shallot ^test
  21         ----------------------------------------------------------------
  22         Found matching pattern after 99133 tries: testvztz3tfoiofv.onion
  23         ----------------------------------------------------------------
  24         -----BEGIN RSA PRIVATE KEY-----
  25         MIICXgIBAAKBgQC3R85m6NQaA1ZjaYqvz1hvFIjbL4RtKdJbG8hlC9xEBkvfr/BG
  26         8Z5vDiUzdbDt8mEBuZUDanx80uGJvbXTgmczX0UlkEOgGiZ8RKpnsbKaf/EJNrIw
  27         T7MSXQmWNcm22nDeViV7fwy+Usyal2RE5cdVCFsPtEbVZqCumlKkEgCyFwIDBAZ7
  28         AoGBAJSa2cGuru/XhzJAEAIwHZbgPDnum9T/srOYxUKW6afHZeOu5S4Cclwb+xb/
  29         pGOtzn71XZfCKMfiVdxB/f3XTcRrYB2VnBoNToTD7WfH6DksdDf4zunqiEjvxi9K
  30         R+tKhxmF7OedrRt8wIhUmFd1E2Q9nbTHI6icdB4kR4QkYKZzAkEA5M6samK7+495
  31         6SWpRXiePIs7sHKWuxdCrG7kW5RNJrv2CcGYwK46TPcaXBcRfM4eq9+9PGoKi0IO
  32         gSpOZ5vRYQJBAM0QAZYTZ6ApD014x372MX1ZNofuYL/+XF8ZPZV6Sh4+9MUBuNPb
  33         yL7BENDr6pX4Zm6OepvAphhCa4vGno2pHncCQQCQnfhUCHANU4bjtX4EOoI63WDq
  34         UwBOeIWxu0YvGt7Z25Dg9CNz/aX8UZIoj6VyKxLRbR9+K3mNrNgaopW+ZDKzAkEA
  35         ttgTK1ALe+3v+5H+Ez1SvFPREDFcHihrfD1Ipc5zicY9ixTArgdyZvk+Pi+AMBVV
  36         sL2HWvjRLEAgRclvKfkwWwJAFtM+BIGRM5me+fMALuBBEtKnbJ6maflsyucErEb0
  37         pIIBkovF5oyWO3lSBmtStJIANNkHOg8aXqjcgPKusDN7CQ==
  38         -----END RSA PRIVATE KEY-----
  39
  40 If you place the RSA private key (including its header and footer) in a file
  41 called *private_key* in the `HiddenServiceDir` you specified in your torrc, (If
  42 you don't know what that means, [read the Tor man page][tor-manual]. If you
  43 *still* don't understand, Shallot probably isn't for you.) then when you restart
  44 your Tor, a *hostname* file will be created in `HiddenServiceDir` that contains
  45 your shiny new .onion address.
  46
  47 On the Security of Generated Host Names
  48 ---------------------------------------
  49 It is sometimes said that host names generated by Shallot are less secure than
  50 the host names generated by Tor. This is false. Shallot doesn't generate .onions
  51 by doing anything different than Tor does, it just does it repeatedly. After a
  52 while, you get a name that matches your requirements.
  53
  54 A History of Shallot
  55 --------------------
  56 Shallot has a long history in [Onion Land][hs]. In its original incarnation,
  57 Shallot was originally written by a mysterious Onion Lander called Bebop, who
  58 created its predecessor, tor-crypt-0.0.1, at some unknown time in the distant
  59 past. That quickly(?) evolved into onionhash 0.0.2 and 0.0.3, until Bebop and
  60 [Bebop's New Home in Onionspace](http://torlandypjxiligx.onion/) mysteriously
  61 vanished. At this point, it was picked up by &#96;Orum, who gave Shallot its
  62 current name, and went through three versions until &#96;Orum's site,
  63 [hangman - hidden (in plan) site][hangman], went down. I (katmagic) got
  64 Shallot's sources from [Tas's site][tasweb] and put them into a Git repository.
  65 I made a few modifications, wrote a new README, and put the whole thing up on
  66 GitHub for all to see.
  67
  68 [hs]: https://www.torproject.org/docs/hidden-services
  69 [hangman]: http://hangman5naigg7rr.onion/
  70 [tasweb]: http://taswebqlseworuhc.onion/
  71 [tor]: https://www.torproject.org/
  72 [tor-manual]: https://www.torproject.org/docs/tor-manual