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/-v)
  48   -o        : Optimize RSA key size to improve SHA-1 hashing speed
  49   -p        : Print 'pattern' help and exit (requires pattern)
  50   -v        : Verbose mode (debugging)
  51   -f <file> : Write output to <file>
  52   -t count  : Forces exactly count threads to be spawned
  53   -e limit  : Manually define the limit for e
  54 Version: 0.0.3
  55
  56 $ ./shallot -p foo
  57 base32 alphabet allows letters [a-z] and digits [2-7]
  58 pattern can be a POSIX-style regular expression, e.g.
  59   xxx           must contain 'xxx'
  60   bar$          must end with 'bar'
  61   ^foo          must begin with 'foo'
  62   b[a4]r        may contain leetspeech ;)
  63   ^ab|^cd       must begin with 'ab' or 'cd'
  64   [a-z]{16}     must contain letters only, no digits
  65   ^dusk.*dawn$  must begin with 'dusk' and end with 'dawn'
  66
  67 $ ./shallot ^test
  68 ----------------------------------------------------------------
  69 Found matching pattern after 99133 tries: testvztz3tfoiofv.onion
  70 ----------------------------------------------------------------
  71 -----BEGIN RSA PRIVATE KEY-----
  72 MIICXgIBAAKBgQC3R85m6NQaA1ZjaYqvz1hvFIjbL4RtKdJbG8hlC9xEBkvfr/BG
  73 8Z5vDiUzdbDt8mEBuZUDanx80uGJvbXTgmczX0UlkEOgGiZ8RKpnsbKaf/EJNrIw
  74 T7MSXQmWNcm22nDeViV7fwy+Usyal2RE5cdVCFsPtEbVZqCumlKkEgCyFwIDBAZ7
  75 AoGBAJSa2cGuru/XhzJAEAIwHZbgPDnum9T/srOYxUKW6afHZeOu5S4Cclwb+xb/
  76 pGOtzn71XZfCKMfiVdxB/f3XTcRrYB2VnBoNToTD7WfH6DksdDf4zunqiEjvxi9K
  77 R+tKhxmF7OedrRt8wIhUmFd1E2Q9nbTHI6icdB4kR4QkYKZzAkEA5M6samK7+495
  78 6SWpRXiePIs7sHKWuxdCrG7kW5RNJrv2CcGYwK46TPcaXBcRfM4eq9+9PGoKi0IO
  79 gSpOZ5vRYQJBAM0QAZYTZ6ApD014x372MX1ZNofuYL/+XF8ZPZV6Sh4+9MUBuNPb
  80 yL7BENDr6pX4Zm6OepvAphhCa4vGno2pHncCQQCQnfhUCHANU4bjtX4EOoI63WDq
  81 UwBOeIWxu0YvGt7Z25Dg9CNz/aX8UZIoj6VyKxLRbR9+K3mNrNgaopW+ZDKzAkEA
  82 ttgTK1ALe+3v+5H+Ez1SvFPREDFcHihrfD1Ipc5zicY9ixTArgdyZvk+Pi+AMBVV
  83 sL2HWvjRLEAgRclvKfkwWwJAFtM+BIGRM5me+fMALuBBEtKnbJ6maflsyucErEb0
  84 pIIBkovF5oyWO3lSBmtStJIANNkHOg8aXqjcgPKusDN7CQ==
  85 -----END RSA PRIVATE KEY-----
  86
  87 The generated key can now be saved as file 'private_key' in your
  88 HiddenServiceDir. Afterwards reload Tor (e.g. by sending SIGHUP)
  89 and you should be reachable as testvztz3tfoiofv.onion.
  90
  91
  92 SECURITY
  93 ~~~~~~~~
  94 Shallot generates a lot of keys in a non-standard fashion, by varying
  95 e. While some may  debate that this leads to weaker  keys, all sanity
  96 checks found in  PKCS#1 v2.1 are strictly followed,  so I don't worry
  97 too much. Please feel free to disagree with me.
  98
  99
 100 PERFORMANCE
 101 ~~~~~~~~~~~
 102 First of all, you cannot create any hash you want (in adequate time).
 103 If you could easily find collisions on the first half (80 bit) of the
 104 SHA1 hash, Torland would be in serious trouble.
 105
 106 The speed of the worker() loop can be divided in:
 107
 108 +-------------------------+
 109 |    Function | CPU usage |
 110 |-------------+-----------|
 111 |    Copy CTX |      1.5% |
 112 | Endian swap |      0.1% |
 113 |        Hash |     67.9% |
 114 |  B32-encode |     21.9% |
 115 |  Regex eval |      8.6% |
 116 +-------------------------+
 117        *** YMMV. ***
 118
 119 On my 1.5GHz x86-machine, I get about 500k hashes/sec.
 120 +---------------------------------------------+
 121 | chars | ~number of tries | ~time @ 500 KH/s |
 122 |-------+------------------+------------------|
 123 |     1 |      32^1  =  32 |          < 1 sec |
 124 |     2 |      32^2  =  1k |          < 1 sec |
 125 |     3 |      32^3  = 32k |          < 1 sec |
 126 |     4 |      32^4  =  1m |            2 sec |
 127 |     5 |      32^5  = 32m |            1 min |
 128 |     6 |      32^6  =  1g |           30 min |
 129 |     7 |      32^7  = 32g |            1 day |
 130 |     8 |      32^8  =  1t |          25 days |
 131 |     9 |      32^9  = 32t |        2.5 years |
 132 .       .                  .                  .
 133 .       .                  .                  .
 134 |    16 |      32^16 =  1y |         too long |
 135 +---------------------------------------------+
 136
 137 Note: you can speed it up if you're only interested in a certain
 138       string to appear somewhere, instead of at a fixed position
 139       like the beginning of the hash. Also you could make use of
 140       'leetspeech', therefore allowing both, e.g. [3e] or [7t]
 141
 142
 143 BUGS
 144 ~~~~
 145 -p still requires a pattern to be present, even though it is not
 146   used.  (e.g. `./shallot -p foo`)
 147 OpenBSD has terrible pthreading, and thus needs a ugly hack that
 148   fork()s instead of threading, but I have neglected to add this
 149   yet.
 150 There is a timing-related bug that is known to occur on GENERIC
 151   systems.  No debug info yet.  :(
 152
 153
 154 TODO
 155 ~~~~
 156 High priority:
 157 * Reverse base32 regex encoding (regex accelation, base32 bypass)
 158 * Optimize SHA1_Final() (use my own function that only produces half
 159     of a SHA-1 hash)
 160 * Reduce amount of data that is rehashed at byte length thresholds
 161 * Adjust default e limit for optimal hashing speed
 162
 163 Medium priority:
 164 * fix known bugs (namely pthreading bug)
 165 * support hardware acceleration (what cards would even work?)
 166 * prime pooling to speed up generation of "tor-compliant" domains
 167 * more of command line options (flags) so you can fine tune hashing
 168
 169 Low priority:
 170 * a config script that checks for all the headers (use autoconf?)
 171 * allow -m to be used with -d/-v (periodically write status to file)
 172 * make sure the requested hash contains base32 chars (2-7, a-z) only
 173 * make sure the requested hash is valid (not longer that 16 chars)
 174