README

About:
------

Eschalot is a Tor hidden service name generator, it allows one to produce
a (partially) customized vanity .onion address using a brute-force method.

See https://torproject.org for more information about the Tor network
and https://torproject.org/docs/hidden-services for the hidden services
documentation.

Why eschalot? Well, eschalot is a different name for shallot and it is
a fork of an older .onion names generator called shallot.

See https://github.com/katmagic/Shallot for information about the shallot
and also see the History section at the end of this document.

Eschalot is distributed in source form under BSD license. It should compile
on any Unix or Linux system, but might need some minor modifications.

It was developed and most extensively tested on OpenBSD, but was also tested
to compile and run on DragonFlyBSD, FreeBSD, CentOS Linux, and couple other
mainstream Linux distributions whose names I do not recall at the moment.
Various combinations of big/little endian platforms, 32bit/64bit platforms,
and gcc/pcc/llvm/clang static analizer were tested. Many bugs were uncovered,
some were fixed, some are still there - see TODO list if interested.



Compilation:
------------

Eschalot requires OpenSSL-0.9.7-or-later libraries with source headers.

You will also need a make utility (either BSD or GNU make will do) and
a C compiler (gcc, pcc, or llvm/clang).

Download the latest version of eschalot (currently eschalot-1.2.0), open a
terminal emulator, such as xterm, and change directory to where you saved
the eschalot-1.2.0.tar.gz archive (for examle /home/username/Download);

	$ cd Download
	$ tar xzvf eschalot-1.2.0.tar.gz
	$ cd eschalot-1.2.0
	$ make

To use a different (other than your system default) C compiler (such as pcc):

	$ make clean
	$ env CC=pcc make

If compilation fails, see some hints below under "Compilation Troubleshooting"
close to the end of this document.

If make succeeds, you might want to run a simple functionality test/demo with

	$ make test

This will use the included worgen utility to create a test wordlist out of the
three small wordlists included with the distribution, will save the list to
'wordlist.txt', and will launch eschalot running with 4 threads to start
looking for the onion names with the prefixes in the wordlist.txt file.
The results will be redirected to the 'results.txt' file. This test needs
a fairly fast machine with at least 250Mb of RAM.

To remove the test files execute

	$ make cleantest

To remove the compiled binaries execute

	$ make clean

To cleanup everything execute

	$ make cleanall



Example output from 'make test':
--------------------------------

$ make test
cc -std=c99 -O2 -fPIC -finline-functions -Wall -W -Wunused -pedantic -Wpointer-arith  -Wreturn-type -Wstrict-prototypes  -Wmissing-prototypes -Wshadow -Wcast-qual -Wextra -o eschalot eschalot.c -lpthread -lssl -lcrypto
cc -std=c99 -O2 -fPIC -finline-functions -Wall -W -Wunused -pedantic -Wpointer-arith  -Wreturn-type -Wstrict-prototypes  -Wmissing-prototypes -Wshadow -Wcast-qual -Wextra -o worgen worgen.c

./worgen 8-16 top150adjectives.txt 3-16 top400nouns.txt 3-16 top1000.txt 3-16 > wordlist.txt
Will be producing 8-16 character long word combinations.
Reading 3-16 characters words from top150adjectives.txt.
Reading 3-16 characters words from top400nouns.txt.
Reading 3-16 characters words from top1000.txt.
Loading words from top150adjectives.txt.
Loaded 150 words from top150adjectives.txt.
Loading words from top400nouns.txt.
Loaded 400 words from top400nouns.txt.
Loading words from top1000.txt.
Loaded 974 words from top1000.txt.
Working. 100% complete, 31122412 words (approximately 377Mb) produced.
Final count: 31366539 word combinations.

./eschalot -vct4 -f wordlist.txt > results.txt
Verbose, continuous, no digits, 4 threads, prefixes 8-16 characters long.
Reading words from wordlist.txt, please wait...
Loaded 31366539 words.
Sorting the word hashes and removing duplicates.
Final word count: 31363570.
Thread #1 started.
Thread #2 started.
Thread #3 started.
Thread #4 started.
Running, collecting performance data...
Found a key for acidfall (8) - acidfalleyt3kkva.onion
Total hashes: 131241356, running time: 10 seconds, hashes per second: 13124135
Found a key for redglass (8) - redglass6i2pxool.onion
Found a key for loudwalk (8) - loudwalk72kvhr4n.onion
Found a key for illarteye (9) - illarteyedjxf3pj.onion
Total hashes: 394606458, running time: 30 seconds, hashes per second: 13153548
Found a key for cutcolor (8) - cutcolorxqxz7ck4.onion
Found a key for safefold (8) - safefold7hmcigr7.onion
Found a key for tallidea (8) - tallideac5zyn3f7.onion
Found a key for wetactago (9) - wetactagot7b42kx.onion
Found a key for pooryear (8) - pooryearxutsizhe.onion
^C*** Signal SIGINT in eschalot-1.2.0 (test)



Usage:
------

Type
	$ ./eschalot
and
	$ ./worgen

without any options to get a quick usage information.


To search using 4 threads (if your CPU has 4 cores), in a verbose mode,
continuing to search after an .onion address is found, looking for a single
prefix "test":

	$ ./eschalot -t4 -v -c -p test

or simply

	$ ./eschalot -vct4 -p test

To search using a regular expression looking for names starting with "test"
or ending with "exam":

	$ ./eschalot -vct4 -r "^test|exam$"

To search for a single prefix "hello" using one thread, redirecting the
output to a file named "results.txt", exiting after the first name is found:

	$ ./eschalot -p hello >> results.txt

To search for prefixes from 8 to 10 characters long from a file named
"wordlist.txt" using 6 threads, in continuous and verbose mode,
redirecting the results to a file:

	$ ./eschalot -vct6 -l8-10 -f wordlist.txt >> results.txt

If eschalot is running on a different machine than will host the onion
service, then it is good to store the results in an encrypted file without
hitting the disk in plain text.  That is easy to do by piping to gpg:

        $ ./eschalot -vct3 -p test | gpg --trust-model always --encrypt \
	    --recipient 0xfakefakefakefakefakefakefake > results.gpg


Generating a wordlist:
----------------------

You can use the included utility "worgen" to generate large wordlists for
eschalot. This utility is far from complete and is not very user friendly,
but can be used if needed. To demonstrate by example:

Generate a (relatively small) list of 8 to 12 character long words by
mixing 3-10 character words from top1000.txt file, 3-6 character words
from top400nouns.txt, and 3-6 character words from top140adjectives.txt,
redirect the results to wordlist.txt:

	$ ./worgen 8-12 top1000.txt 3-10 top400nouns.txt \
	  3-6 top150adjectives.txt 3-6 > wordlist.txt


Generate a large (~1.2Gb) file of 10 character long words by mixing twice
words from a single file:

	$ ./worgen 10-10 nouns.txt 3-10 nouns.txt 3-10 > wordlist.txt

At this point you might want to try running

	$ ./eschalot -vct6 -l 10-10 -f wordlist.txt > results.txt

to test if your system can load a large file into memory.

The result should look something like this:

$ ./eschalot -vct6 -l 10-10 -f wordlist.txt > results.txt 
Verbose, continuous, no digits, 6 threads, prefixes 10-10 characters long.
Reading words from wordlist.txt, please wait...
Loaded 110792061 words.
Sorting the word hashes and removing duplicates.
Final word count: 110558812.
Thread #1 started.
Thread #2 started.
Thread #3 started.
Thread #4 started.
Thread #5 started.
Thread #6 started.
Running, collecting performance data...
Found a key for museumazof (10) - museumazofgsihx2.onion
Found a key for balzacnick (10) - balzacnickaxtbd4.onion
Found a key for methodmoor (10) - methodmooraudcft.onion
Found a key for gneissbutt (10) - gneissbuttieicps.onion
Found a key for todcorypha (10) - todcoryphadr7zv4.onion
Found a key for pleveniyar (10) - pleveniyarpa3hlx.onion
Found a key for caputwight (10) - caputwightz46r3n.onion
Found a key for mervensalp (10) - mervensalpskbwad.onion
Found a key for hallelenid (10) - hallelenidmhln6o.onion
Found a key for quotalysis (10) - quotalysisadbc57.onion
Found a key for longabarth (10) - longabarthvvdjpw.onion
Found a key for vannlozier (10) - vannlozierwqadcv.onion
Found a key for uriahcadre (10) - uriahcadreac7ujz.onion
Found a key for denmarkjew (10) - denmarkjewfyozqj.onion
Found a key for kochiiclod (10) - kochiiclodifftuw.onion
Found a key for fondusamba (10) - fondusambaialjro.onion
^C

As you see, it finds a lot of prefixes in just a few seconds, but most of them
are useless - that's the downside of using a really large wordlist with either
junk or extremely uncommon words combinations in it. Experiment with it! :)



Security of generated keys:
---------------------------

Original note from Shallot:

It is sometimes claimed that private keys generated by Shallot are less
secure than those generated by Tor. This is false. Although Shallot generates
a keypair with an unusually large public exponent e, it performs all of the
sanity checks specified by PKCS #1 v2.1 (directly in sane_key), and then
performs all of the sanity checks that Tor does when it generates an RSA
keypair (by calling the OpenSSL function RSA_check_key).


Eschalot additions:

Now the public exponent is limited to the range of 
(0xFFFFFF + 2) to (0xFFFFFFFF) - basically, odd values that take at least,
and no more than, 4 bytes.

In addition, unlike shallot, after the RSA key has been finalized, the
.onion name is regenerated using the same procedure as used in the official
TOR client - this filters out the occasional bogus .onions that shallot
generated occasionally (and eschalot does too - this is a bug I have not
tracked down yet).

Now, there is nothing stopping the TOR developers from modifying the TOR
client to only accept manually imported keys with public exponent equal,
lets say, 65537 and nothing else, but that would be silly of them. It would
not improve TOR's performance much or serve any other purpose, but to
knock offline several well established hidden websites that have been using
shallot-generated keys for years. I would not worry about it.



Performance:
------------

Depends on how fast your CPU is and how many cores you have, but generally
speaking it's a bit faster than shallot. Up to twice as fast in some cases,
but it depends greatly on how fast the OpenSSL's SHA1 implementation is on
the system. Some use hand-optimized assembly, some use C versions.

Wordlist mode is obviously slower than a single fixed prefix mode, but not
by much. The difference between searching in a 100 words list and a 100 million
words list is negligible due to the binary search and hashed tree data
storage. Of course, that is if the whole wordlist fits in RAM completely.

Memory needed is approximately 0.5-0.7 of the size of the wordlist size
on disk (yes, eschalot needs less memory than the file takes due to the words
getting converted into binary format and stored in a sort of a hashed tree).



Compilation Troubleshooting:
----------------------------

1). Does the error message you are getting give you any hints?


2). If the error message complains that make/gmake/gcc/cc cannot be found,
you will need to install the make/gmake utility and gcc or some other C
compiler. Some of the Linuxes split the gcc package into several smaller ones
- you will need the one that says "GNU C Compiler" or something like that.

Note: most of the mainstream Linuxes do not come with a compiler by default
theese days even if you choose a complete - often 5-10Gb - installation.  
(Yeah, that was a shock for me too), but it's fairly easy to install it by
using your operating system's software manager.


3). If it says something like "SHA1*** / RSA*** /BN_*** function not defined"
or "missing <openssl/***.h> header", you will need to make sure you not
only have the dynamic OpenSSL libraries installed, but also the header files.
On Linuxes, they are sometimes distributed in a different package from the
main OpenSSL and are called something like "OpenSSL-development" or
"OpenSSL-sources-and-headers" or something like that - look around.


4). If you get an error message about 'htobe32' function not being defined,
you can try using a locally-supplied copy by compiling with

	$ env CFLAGS=-DNEED_HTOBE32 make

Same if your system does not have strnlen - try

	$ env CFLAGS=-DNEED_STRNLEN make

Or might even have to define both like this:

	$ env CFLAGS="-DNEED_HTOBE32 -DNEED_STRNLEN" make


5). If all of the above fails, take a look inside the Makefile, and see if
you need to disable or enable some additional C flags.


6). If your error message says something about endian.h, take a look at the
beginning of the eschalot.c file, see how that file is being included.
You might need to adjust it a bit (that part needs work - see TODO list).


7). If all else fails, send me an email or post something on the feedback
forum. I'll be happy to hear any feedback, positive or negative, and will try
to help.



Bugs and ToDo list:
-------------------

0). Highest priority bug:
Every so often, while searching in a wordlist mode, eschalot finds the
right prefix, but then, after finalizing the key and regenerating the .onion
name, the result is garbage. I suspected my CPU or RAM overheating at first,
but now I tend to think it's a bug in the program (or OpenSSL) somewhere.
It gets detected and rejected and a message is printed on STDERR, but it's
a big waste of hash cycles. Have to track it down.

1). worgen dumps core on 32-bit OpenBSD when using fairly large input
wordlists (triggers stack smash protection). Works fine on 64-bit systems.

2). I tried to optimize the main loop somewhat, but the wordlist loading
could use some improvement - realloc'ing 8 bytes at a time is slow (was
concerned about total memory used when loading large files when I did it).

3). Need better statistics with estimated time needed predictions.

4). Half the variables are global - does not hurt in this case, but is ugly.

5). Print out the public exponent used when a key is found.

6). Write a manpage.

7). Optimize and improve the worgen utility, it was a quick hack.

8). More testing on different OSes, finalize the htobe32/strnlen defines mess.

9). Attempt to implement a GPU hashing mode for Linux.

10). Add a local SHA1 function written in assembly for sparc/sparc64.

11). Make it compile on windows and provide windows binary.

12). Go over the numerous TODOs in the code and address them.

13). Generate one ultimate wordlist with good word combinations 8-16 chars
long, about 5-10Gb in size total, so it could be used to search for a
specific lengths even if the whole thing cannot fit in RAM at once. Perhaps
grab all the phrases and word combinations from a few hundred ebooks
instead of generating randomly mixed rubbish?

14). Move the defines, includes, and functions shared between eschalot and
worgen into "common.h/common.c" files.

15). Add a real self-test with fixed initial RSA key, compare a few hundred
generated .onion names to a known good file. Or something like that.
Make it all driven through the Makefile to simplify testing on different
platforms.


History:
--------

Circa 2006, a person with a nickname Cowboy Bebop created the original
onionhash-0.0.1, which evolved into onionhash-0.0.2 and 0.0.3, until Bebop
and his home at torlandypjxiligx.onion mysteriously vanished.

At this point, it was picked up by someone called Orum, who renamed the
onionhash to shallot and went through three versions until Orum's site at
hangman5naigg7rr.onion disappeared.

Another concerned OnionLand citizen Katmagic got shallot's sources from
taswebqlseworuhc.onion and put them into a Git repository. Made a few
modifications, wrote a new README, and put the whole thing up on GitHub.

I stumbled on the project at some point and had a few ideas on how to make
it more flexible. However, the changes I planned to make were too extensive
to consider simply patching shallot, so I decided to fork it and work on
it for my own private use. After messing with it (very) occasionally for
couple of months, I figured it might be of use to some other TOR enthusiasts,
even though I would not call my remake of shallot "production ready".

Initially I named my project "scallion", however, just a few days ago, I have
learned of yet another .onion names generator recently released which was,
unsurprisingly, named scallion, so I renamed my project to "eschalot".

See https://github.com/lachesis/scallion for more details on scallion.

It's all about choices and now you have several!

P.S. Following the tradition set forth by the previous authors, I will
remain anonymous for the time being.

P.P.S. Sending my greetings and thanks to all the people who worked on this
project before me and kept it alive over the years!

--Unperson Hiro
19 February 2013