README.asciidoc

   1 Shallot
   2 =======
   3
   4 About
   5 -----
   6 Shallot allows you to create customized .onion addresses for
   7 link:https://www.torproject.org/[Tor's]
   8 link:https://www.torproject.org/docs/hidden-services[hidden services].
   9 (By customized, it is meant that part of the address can be selected. Choosing
  10 an entire address would take far longer than the universe is believed to have
  11 been 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,
  43 link:https://www.torproject.org/docs/tor-manual[read the Tor man page]. If you
  44 *still* don't understand, Shallot probably isn't for you.) then when you restart
  45 your Tor, a `hostname` file will be created in `HiddenServiceDir` that contains
  46 your shiny new .onion address.
  47
  48 On the Security of Generated Keypairs
  49 -------------------------------------
  50 It is sometimes claimed that private keys generated by Shallot are less secure
  51 than those generated by Tor. This is false. Although Shallot generates a
  52 keypair with an unusually large public exponent e, it performs all of the
  53 sanity checks specified by PKCS #1 v2.1 (directly in sane_key), and then
  54 performs all of the sanity checks that Tor does when it generates an RSA
  55 keypair (by calling the OpenSSL function RSA_check_key).
  56
  57 Performance
  58 -----------
  59 .Time to Generate a .onion with a Given Number of Initial Characters on a 1.5Ghz Processor
  60 [align="right",float="left",width="30%"]
  61 |=======================================
  62 |characters | time to generate (approx.)
  63 |         1 |         less than 1 second
  64 |         2 |         less than 1 second
  65 |         3 |         less than 1 second
  66 |         4 |                  2 seconds
  67 |         5 |                   1 minute
  68 |         6 |                 30 minutes
  69 |         7 |                      1 day
  70 |         8 |                    25 days
  71 |         9 |                  2.5 years
  72 |        10 |                   40 years
  73 |        11 |                  640 years
  74 |        12 |                10 millenia
  75 |        13 |               160 millenia
  76 |        14 |          2.6 million years
  77 |=======================================
  78
  79 A History of Shallot
  80 --------------------
  81 Shallot has a long history in Onion Land. In its original incarnation, Shallot
  82 was originally written by a mysterious Onion Lander called Bebop, who created
  83 its predecessor, onionhash-0.0.1, at some unknown time in the distant past. That
  84 quickly(?) evolved into onionhash 0.0.2 and 0.0.3, until Bebop and
  85 link:http://torlandypjxiligx.onion/[Bebop's New Home in Onionspace] mysteriously
  86 vanished. At this point, it was picked up by &#96;Orum, who gave Shallot its
  87 current name, and went through three versions until &#96;Orum's site,
  88 link:http://hangman5naigg7rr.onion/[hangman - hidden (in plain) site], went
  89 down. I (katmagic) got Shallot's sources from
  90 link:http://taswebqlseworuhc.onion/[Tas's site] and put them into a Git
  91 repository. I made a few modifications, wrote a new README, and put the whole
  92 thing up on GitHub for all to see.