README

   1 ---------------------------------------------------------------------
   2                             shallot 0.0.3
   3 ---------------------------------------------------------------------
   4
   5 CONTENT
   6 ~~~~~~~
   7 ./
   8 CHANGELOG   - lists the latest improvements/fixes
   9 LICENSE     - for those who believe in copyright
  10 configure   - configures shallot for your system
  11 Makefile    - builds the binary (on most systems)
  12 README      - the file you are reading right now
  13
  14 ./src/      - contains source code for shallot
  15
  16
  17 HISTORY
  18 ~~~~~~~
  19 This program is based on Bebop's program, onionhash-0.0.2.  Since
  20 Bebop has mysteriously disappeared (along with his hidden service
  21 site), I decided to branch the source and improve upon it further
  22 (see CHANGELOG).  However, I owe much of the  credit to Bebop for
  23 the original onionhash, as shallot would not exist without it.
  24
  25
  26 INSTALL
  27 ~~~~~~~
  28 * You need to have a recent version of OpenSSL installed.
  29 * First run the configure script `./configure` and wait.
  30 * Type `make` and pray everything compiles successfully.
  31 * Run the program, get some runts.  Come back tomorrow.
  32
  33
  34 ABOUT
  35 ~~~~~
  36 This program allows you to create customized SHA1 hashes for Tor
  37 hidden services. It's based on THC's Fuzzy Fingerprint technique
  38 (paper available at http://thc.org/papers/ffp.pdf). "Customized"
  39 means, you can choose parts of the hash to match certain regular
  40 expression patterns.
  41
  42 >> example: create private key for test*.onion:
  43
  44 $ ./shallot
  45 Usage: shallot [-dmopv] [-f <file>] [-t count] [-e limit] pattern
  46   -d        : Daemonize (requires -f)
  47   -m        : Monitor mode (incompatible with -f)
  48   -o        : Optimize RSA key size to improve SHA-1 hashing speed
  49   -p        : Print 'pattern' help and exit (requires pattern)
  50   -f <file> : Write output to <file>
  51   -t count  : Forces exactly count threads to be spawned
  52   -e limit  : Manually define the limit for e
  53 Version: 0.0.3
  54
  55 $ ./shallot -p foo
  56 base32 alphabet allows letters [a-z] and digits [2-7]
  57 pattern can be a POSIX-style regular expression, e.g.
  58   xxx           must contain 'xxx'
  59   bar$          must end with 'bar'
  60   ^foo          must begin with 'foo'
  61   b[a4]r        may contain leetspeech ;)
  62   ^ab|^cd       must begin with 'ab' or 'cd'
  63   [a-z]{16}     must contain letters only, no digits
  64   ^dusk.*dawn$  must begin with 'dusk' and end with 'dawn'
  65
  66 $ ./shallot ^test
  67 ----------------------------------------------------------------
  68 Found matching pattern after 99133 tries: testvztz3tfoiofv.onion
  69 ----------------------------------------------------------------
  70 -----BEGIN RSA PRIVATE KEY-----
  71 MIICXgIBAAKBgQC3R85m6NQaA1ZjaYqvz1hvFIjbL4RtKdJbG8hlC9xEBkvfr/BG
  72 8Z5vDiUzdbDt8mEBuZUDanx80uGJvbXTgmczX0UlkEOgGiZ8RKpnsbKaf/EJNrIw
  73 T7MSXQmWNcm22nDeViV7fwy+Usyal2RE5cdVCFsPtEbVZqCumlKkEgCyFwIDBAZ7
  74 AoGBAJSa2cGuru/XhzJAEAIwHZbgPDnum9T/srOYxUKW6afHZeOu5S4Cclwb+xb/
  75 pGOtzn71XZfCKMfiVdxB/f3XTcRrYB2VnBoNToTD7WfH6DksdDf4zunqiEjvxi9K
  76 R+tKhxmF7OedrRt8wIhUmFd1E2Q9nbTHI6icdB4kR4QkYKZzAkEA5M6samK7+495
  77 6SWpRXiePIs7sHKWuxdCrG7kW5RNJrv2CcGYwK46TPcaXBcRfM4eq9+9PGoKi0IO
  78 gSpOZ5vRYQJBAM0QAZYTZ6ApD014x372MX1ZNofuYL/+XF8ZPZV6Sh4+9MUBuNPb
  79 yL7BENDr6pX4Zm6OepvAphhCa4vGno2pHncCQQCQnfhUCHANU4bjtX4EOoI63WDq
  80 UwBOeIWxu0YvGt7Z25Dg9CNz/aX8UZIoj6VyKxLRbR9+K3mNrNgaopW+ZDKzAkEA
  81 ttgTK1ALe+3v+5H+Ez1SvFPREDFcHihrfD1Ipc5zicY9ixTArgdyZvk+Pi+AMBVV
  82 sL2HWvjRLEAgRclvKfkwWwJAFtM+BIGRM5me+fMALuBBEtKnbJ6maflsyucErEb0
  83 pIIBkovF5oyWO3lSBmtStJIANNkHOg8aXqjcgPKusDN7CQ==
  84 -----END RSA PRIVATE KEY-----
  85
  86 The generated key can now be saved as file 'private_key' in your
  87 HiddenServiceDir. Afterwards reload Tor (e.g. by sending SIGHUP)
  88 and you should be reachable as testvztz3tfoiofv.onion.
  89
  90
  91 SECURITY
  92 ~~~~~~~~
  93 Shallot generates a lot of keys in a non-standard fashion, by varying
  94 e. While some may  debate that this leads to weaker  keys, all sanity
  95 checks found in  PKCS#1 v2.1 are strictly followed,  so I don't worry
  96 too much. Please feel free to disagree with me.
  97
  98
  99 PERFORMANCE
 100 ~~~~~~~~~~~
 101 First of all, you cannot create any hash you want (in adequate time).
 102 If you could easily find collisions on the first half (80 bit) of the
 103 SHA1 hash, Torland would be in serious trouble.
 104
 105 The speed of the worker() loop can be divided in:
 106
 107 +-------------------------+
 108 |    Function | CPU usage |
 109 |-------------+-----------|
 110 |    Copy CTX |      1.5% |
 111 | Endian swap |      0.1% |
 112 |        Hash |     67.9% |
 113 |  B32-encode |     21.9% |
 114 |  Regex eval |      8.6% |
 115 +-------------------------+
 116        *** YMMV. ***
 117
 118 On my 1.5GHz x86-machine, I get about 500k hashes/sec.
 119 +---------------------------------------------+
 120 | chars | ~number of tries | ~time @ 500 KH/s |
 121 |-------+------------------+------------------|
 122 |     1 |      32^1  =  32 |          < 1 sec |
 123 |     2 |      32^2  =  1k |          < 1 sec |
 124 |     3 |      32^3  = 32k |          < 1 sec |
 125 |     4 |      32^4  =  1m |            2 sec |
 126 |     5 |      32^5  = 32m |            1 min |
 127 |     6 |      32^6  =  1g |           30 min |
 128 |     7 |      32^7  = 32g |            1 day |
 129 |     8 |      32^8  =  1t |          25 days |
 130 |     9 |      32^9  = 32t |        2.5 years |
 131 .       .                  .                  .
 132 .       .                  .                  .
 133 |    16 |      32^16 =  1y |         too long |
 134 +---------------------------------------------+
 135
 136 Note: you can speed it up if you're only interested in a certain
 137       string to appear somewhere, instead of at a fixed position
 138       like the beginning of the hash. Also you could make use of
 139       'leetspeech', therefore allowing both, e.g. [3e] or [7t]
 140
 141
 142 BUGS
 143 ~~~~
 144 -p still requires a pattern to be present, even though it is not
 145   used.  (e.g. `./shallot -p foo`)
 146 OpenBSD has terrible pthreading, and thus needs a ugly hack that
 147   fork()s instead of threading, but I have neglected to add this
 148   yet.
 149 There is a timing-related bug that is known to occur on GENERIC
 150   systems.  No debug info yet.  :(
 151
 152
 153 TODO
 154 ~~~~
 155 High priority:
 156 * Reverse base32 regex encoding (regex accelation, base32 bypass)
 157 * Optimize SHA1_Final() (use my own function that only produces half
 158     of a SHA-1 hash)
 159 * Reduce amount of data that is rehashed at byte length thresholds
 160 * Adjust default e limit for optimal hashing speed
 161
 162 Medium priority:
 163 * fix known bugs (namely pthreading bug)
 164 * support hardware acceleration (what cards would even work?)
 165 * prime pooling to speed up generation of "tor-compliant" domains
 166 * more of command line options (flags) so you can fine tune hashing
 167
 168 Low priority:
 169 * a config script that checks for all the headers (use autoconf?)
 170 * allow -m to be used with -d (periodically write status to file)
 171 * make sure the requested hash contains base32 chars (2-7, a-z) only
 172 * make sure the requested hash is valid (not longer that 16 chars)
 173