1About: 2------ 3 4Eschalot is a Tor hidden service name generator, it allows one to produce 5a (partially) customized vanity .onion address using a brute-force method. 6 7See https://torproject.org for more information about the Tor network 8and https://torproject.org/docs/hidden-services for the hidden services 9documentation. 10 11Why eschalot? Well, eschalot is a different name for shallot and it is 12a fork of an older .onion names generator called shallot. 13 14See https://github.com/katmagic/Shallot for information about the shallot 15and also see the History section at the end of this document. 16 17Eschalot is distributed in source form under BSD license. It should compile 18on any Unix or Linux system, but might need some minor modifications. 19 20It was developed and most extensively tested on OpenBSD, but was also tested 21to compile and run on DragonFlyBSD, FreeBSD, CentOS Linux, and couple other 22mainstream Linux distributions whose names I do not recall at the moment. 23Various combinations of big/little endian platforms, 32bit/64bit platforms, 24and gcc/pcc/llvm/clang static analizer were tested. Many bugs were uncovered, 25some were fixed, some are still there - see TODO list if interested. 26 27 28 29Compilation: 30------------ 31 32Eschalot requires OpenSSL-0.9.7-or-later libraries with source headers. 33 34You will also need a make utility (either BSD or GNU make will do) and 35a C compiler (gcc, pcc, or llvm/clang). 36 37Download the latest version of eschalot (currently eschalot-1.2.0), open a 38terminal emulator, such as xterm, and change directory to where you saved 39the eschalot-1.2.0.tar.gz archive (for examle /home/username/Download); 40 41 $ cd Download 42 $ tar xzvf eschalot-1.2.0.tar.gz 43 $ cd eschalot-1.2.0 44 $ make 45 46To use a different (other than your system default) C compiler (such as pcc): 47 48 $ make clean 49 $ env CC=pcc make 50 51If compilation fails, see some hints below under "Compilation Troubleshooting" 52close to the end of this document. 53 54If make succeeds, you might want to run a simple functionality test/demo with 55 56 $ make test 57 58This will use the included worgen utility to create a test wordlist out of the 59three small wordlists included with the distribution, will save the list to 60'wordlist.txt', and will launch eschalot running with 4 threads to start 61looking for the onion names with the prefixes in the wordlist.txt file. 62The results will be redirected to the 'results.txt' file. This test needs 63a fairly fast machine with at least 250Mb of RAM. 64 65To remove the test files execute 66 67 $ make cleantest 68 69To remove the compiled binaries execute 70 71 $ make clean 72 73To cleanup everything execute 74 75 $ make cleanall 76 77 78 79Example output from 'make test': 80-------------------------------- 81 82$ make test 83cc -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 84cc -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 85 86./worgen 8-16 top150adjectives.txt 3-16 top400nouns.txt 3-16 top1000.txt 3-16 > wordlist.txt 87Will be producing 8-16 character long word combinations. 88Reading 3-16 characters words from top150adjectives.txt. 89Reading 3-16 characters words from top400nouns.txt. 90Reading 3-16 characters words from top1000.txt. 91Loading words from top150adjectives.txt. 92Loaded 150 words from top150adjectives.txt. 93Loading words from top400nouns.txt. 94Loaded 400 words from top400nouns.txt. 95Loading words from top1000.txt. 96Loaded 974 words from top1000.txt. 97Working. 100% complete, 31122412 words (approximately 377Mb) produced. 98Final count: 31366539 word combinations. 99 100./eschalot -vct4 -f wordlist.txt > results.txt 101Verbose, continuous, no digits, 4 threads, prefixes 8-16 characters long. 102Reading words from wordlist.txt, please wait... 103Loaded 31366539 words. 104Sorting the word hashes and removing duplicates. 105Final word count: 31363570. 106Thread #1 started. 107Thread #2 started. 108Thread #3 started. 109Thread #4 started. 110Running, collecting performance data... 111Found a key for acidfall (8) - acidfalleyt3kkva.onion 112Total hashes: 131241356, running time: 10 seconds, hashes per second: 13124135 113Found a key for redglass (8) - redglass6i2pxool.onion 114Found a key for loudwalk (8) - loudwalk72kvhr4n.onion 115Found a key for illarteye (9) - illarteyedjxf3pj.onion 116Total hashes: 394606458, running time: 30 seconds, hashes per second: 13153548 117Found a key for cutcolor (8) - cutcolorxqxz7ck4.onion 118Found a key for safefold (8) - safefold7hmcigr7.onion 119Found a key for tallidea (8) - tallideac5zyn3f7.onion 120Found a key for wetactago (9) - wetactagot7b42kx.onion 121Found a key for pooryear (8) - pooryearxutsizhe.onion 122^C*** Signal SIGINT in eschalot-1.2.0 (test) 123 124 125 126Usage: 127------ 128 129Type 130 $ ./eschalot 131and 132 $ ./worgen 133 134without any options to get a quick usage information. 135 136 137To search using 4 threads (if your CPU has 4 cores), in a verbose mode, 138continuing to search after an .onion address is found, looking for a single 139prefix "test": 140 141 $ ./eschalot -t4 -v -c -p test 142 143or simply 144 145 $ ./eschalot -vct4 -p test 146 147To search using a regular expression looking for names starting with "test" 148or ending with "exam": 149 150 $ ./eschalot -vct4 -r "^test|exam$" 151 152To search for a single prefix "hello" using one thread, redirecting the 153output to a file named "results.txt", exiting after the first name is found: 154 155 $ ./eschalot -p hello >> results.txt 156 157To search for prefixes from 8 to 10 characters long from a file named 158"wordlist.txt" using 6 threads, in continuous and verbose mode, 159redirecting the results to a file: 160 161 $ ./eschalot -vct6 -l8-10 -f wordlist.txt >> results.txt 162 163If eschalot is running on a different machine than will host the onion 164service, then it is good to store the results in an encrypted file without 165hitting the disk in plain text. That is easy to do by piping to gpg: 166 167 $ ./eschalot -vct3 -p test | gpg --trust-model always --encrypt \ 168 --recipient 0xfakefakefakefakefakefakefake > results.gpg 169 170 171Generating a wordlist: 172---------------------- 173 174You can use the included utility "worgen" to generate large wordlists for 175eschalot. This utility is far from complete and is not very user friendly, 176but can be used if needed. To demonstrate by example: 177 178Generate a (relatively small) list of 8 to 12 character long words by 179mixing 3-10 character words from top1000.txt file, 3-6 character words 180from top400nouns.txt, and 3-6 character words from top140adjectives.txt, 181redirect the results to wordlist.txt: 182 183 $ ./worgen 8-12 top1000.txt 3-10 top400nouns.txt \ 184 3-6 top150adjectives.txt 3-6 > wordlist.txt 185 186 187Generate a large (~1.2Gb) file of 10 character long words by mixing twice 188words from a single file: 189 190 $ ./worgen 10-10 nouns.txt 3-10 nouns.txt 3-10 > wordlist.txt 191 192At this point you might want to try running 193 194 $ ./eschalot -vct6 -l 10-10 -f wordlist.txt > results.txt 195 196to test if your system can load a large file into memory. 197 198The result should look something like this: 199 200$ ./eschalot -vct6 -l 10-10 -f wordlist.txt > results.txt 201Verbose, continuous, no digits, 6 threads, prefixes 10-10 characters long. 202Reading words from wordlist.txt, please wait... 203Loaded 110792061 words. 204Sorting the word hashes and removing duplicates. 205Final word count: 110558812. 206Thread #1 started. 207Thread #2 started. 208Thread #3 started. 209Thread #4 started. 210Thread #5 started. 211Thread #6 started. 212Running, collecting performance data... 213Found a key for museumazof (10) - museumazofgsihx2.onion 214Found a key for balzacnick (10) - balzacnickaxtbd4.onion 215Found a key for methodmoor (10) - methodmooraudcft.onion 216Found a key for gneissbutt (10) - gneissbuttieicps.onion 217Found a key for todcorypha (10) - todcoryphadr7zv4.onion 218Found a key for pleveniyar (10) - pleveniyarpa3hlx.onion 219Found a key for caputwight (10) - caputwightz46r3n.onion 220Found a key for mervensalp (10) - mervensalpskbwad.onion 221Found a key for hallelenid (10) - hallelenidmhln6o.onion 222Found a key for quotalysis (10) - quotalysisadbc57.onion 223Found a key for longabarth (10) - longabarthvvdjpw.onion 224Found a key for vannlozier (10) - vannlozierwqadcv.onion 225Found a key for uriahcadre (10) - uriahcadreac7ujz.onion 226Found a key for denmarkjew (10) - denmarkjewfyozqj.onion 227Found a key for kochiiclod (10) - kochiiclodifftuw.onion 228Found a key for fondusamba (10) - fondusambaialjro.onion 229^C 230 231As you see, it finds a lot of prefixes in just a few seconds, but most of them 232are useless - that's the downside of using a really large wordlist with either 233junk or extremely uncommon words combinations in it. Experiment with it! :) 234 235 236 237Security of generated keys: 238--------------------------- 239 240Original note from Shallot: 241 242It is sometimes claimed that private keys generated by Shallot are less 243secure than those generated by Tor. This is false. Although Shallot generates 244a keypair with an unusually large public exponent e, it performs all of the 245sanity checks specified by PKCS #1 v2.1 (directly in sane_key), and then 246performs all of the sanity checks that Tor does when it generates an RSA 247keypair (by calling the OpenSSL function RSA_check_key). 248 249 250Eschalot additions: 251 252Now the public exponent is limited to the range of 253(0xFFFFFF + 2) to (0xFFFFFFFF) - basically, odd values that take at least, 254and no more than, 4 bytes. 255 256In addition, unlike shallot, after the RSA key has been finalized, the 257.onion name is regenerated using the same procedure as used in the official 258TOR client - this filters out the occasional bogus .onions that shallot 259generated occasionally (and eschalot does too - this is a bug I have not 260tracked down yet). 261 262Now, there is nothing stopping the TOR developers from modifying the TOR 263client to only accept manually imported keys with public exponent equal, 264lets say, 65537 and nothing else, but that would be silly of them. It would 265not improve TOR's performance much or serve any other purpose, but to 266knock offline several well established hidden websites that have been using 267shallot-generated keys for years. I would not worry about it. 268 269 270 271Performance: 272------------ 273 274Depends on how fast your CPU is and how many cores you have, but generally 275speaking it's a bit faster than shallot. Up to twice as fast in some cases, 276but it depends greatly on how fast the OpenSSL's SHA1 implementation is on 277the system. Some use hand-optimized assembly, some use C versions. 278 279Wordlist mode is obviously slower than a single fixed prefix mode, but not 280by much. The difference between searching in a 100 words list and a 100 million 281words list is negligible due to the binary search and hashed tree data 282storage. Of course, that is if the whole wordlist fits in RAM completely. 283 284Memory needed is approximately 0.5-0.7 of the size of the wordlist size 285on disk (yes, eschalot needs less memory than the file takes due to the words 286getting converted into binary format and stored in a sort of a hashed tree). 287 288 289 290Compilation Troubleshooting: 291---------------------------- 292 2931). Does the error message you are getting give you any hints? 294 295 2962). If the error message complains that make/gmake/gcc/cc cannot be found, 297you will need to install the make/gmake utility and gcc or some other C 298compiler. Some of the Linuxes split the gcc package into several smaller ones 299- you will need the one that says "GNU C Compiler" or something like that. 300 301Note: most of the mainstream Linuxes do not come with a compiler by default 302theese days even if you choose a complete - often 5-10Gb - installation. 303(Yeah, that was a shock for me too), but it's fairly easy to install it by 304using your operating system's software manager. 305 306 3073). If it says something like "SHA1*** / RSA*** /BN_*** function not defined" 308or "missing <openssl/***.h> header", you will need to make sure you not 309only have the dynamic OpenSSL libraries installed, but also the header files. 310On Linuxes, they are sometimes distributed in a different package from the 311main OpenSSL and are called something like "OpenSSL-development" or 312"OpenSSL-sources-and-headers" or something like that - look around. 313 314 3154). If you get an error message about 'htobe32' function not being defined, 316you can try using a locally-supplied copy by compiling with 317 318 $ env CFLAGS=-DNEED_HTOBE32 make 319 320Same if your system does not have strnlen - try 321 322 $ env CFLAGS=-DNEED_STRNLEN make 323 324Or might even have to define both like this: 325 326 $ env CFLAGS="-DNEED_HTOBE32 -DNEED_STRNLEN" make 327 328 3295). If all of the above fails, take a look inside the Makefile, and see if 330you need to disable or enable some additional C flags. 331 332 3336). If your error message says something about endian.h, take a look at the 334beginning of the eschalot.c file, see how that file is being included. 335You might need to adjust it a bit (that part needs work - see TODO list). 336 337 3387). If all else fails, send me an email or post something on the feedback 339forum. I'll be happy to hear any feedback, positive or negative, and will try 340to help. 341 342 343 344Bugs and ToDo list: 345------------------- 346 3470). Highest priority bug: 348Every so often, while searching in a wordlist mode, eschalot finds the 349right prefix, but then, after finalizing the key and regenerating the .onion 350name, the result is garbage. I suspected my CPU or RAM overheating at first, 351but now I tend to think it's a bug in the program (or OpenSSL) somewhere. 352It gets detected and rejected and a message is printed on STDERR, but it's 353a big waste of hash cycles. Have to track it down. 354 3551). worgen dumps core on 32-bit OpenBSD when using fairly large input 356wordlists (triggers stack smash protection). Works fine on 64-bit systems. 357 3582). I tried to optimize the main loop somewhat, but the wordlist loading 359could use some improvement - realloc'ing 8 bytes at a time is slow (was 360concerned about total memory used when loading large files when I did it). 361 3623). Need better statistics with estimated time needed predictions. 363 3644). Half the variables are global - does not hurt in this case, but is ugly. 365 3665). Print out the public exponent used when a key is found. 367 3686). Write a manpage. 369 3707). Optimize and improve the worgen utility, it was a quick hack. 371 3728). More testing on different OSes, finalize the htobe32/strnlen defines mess. 373 3749). Attempt to implement a GPU hashing mode for Linux. 375 37610). Add a local SHA1 function written in assembly for sparc/sparc64. 377 37811). Make it compile on windows and provide windows binary. 379 38012). Go over the numerous TODOs in the code and address them. 381 38213). Generate one ultimate wordlist with good word combinations 8-16 chars 383long, about 5-10Gb in size total, so it could be used to search for a 384specific lengths even if the whole thing cannot fit in RAM at once. Perhaps 385grab all the phrases and word combinations from a few hundred ebooks 386instead of generating randomly mixed rubbish? 387 38814). Move the defines, includes, and functions shared between eschalot and 389worgen into "common.h/common.c" files. 390 39115). Add a real self-test with fixed initial RSA key, compare a few hundred 392generated .onion names to a known good file. Or something like that. 393Make it all driven through the Makefile to simplify testing on different 394platforms. 395 396 397History: 398-------- 399 400Circa 2006, a person with a nickname Cowboy Bebop created the original 401onionhash-0.0.1, which evolved into onionhash-0.0.2 and 0.0.3, until Bebop 402and his home at torlandypjxiligx.onion mysteriously vanished. 403 404At this point, it was picked up by someone called Orum, who renamed the 405onionhash to shallot and went through three versions until Orum's site at 406hangman5naigg7rr.onion disappeared. 407 408Another concerned OnionLand citizen Katmagic got shallot's sources from 409taswebqlseworuhc.onion and put them into a Git repository. Made a few 410modifications, wrote a new README, and put the whole thing up on GitHub. 411 412I stumbled on the project at some point and had a few ideas on how to make 413it more flexible. However, the changes I planned to make were too extensive 414to consider simply patching shallot, so I decided to fork it and work on 415it for my own private use. After messing with it (very) occasionally for 416couple of months, I figured it might be of use to some other TOR enthusiasts, 417even though I would not call my remake of shallot "production ready". 418 419Initially I named my project "scallion", however, just a few days ago, I have 420learned of yet another .onion names generator recently released which was, 421unsurprisingly, named scallion, so I renamed my project to "eschalot". 422 423See https://github.com/lachesis/scallion for more details on scallion. 424 425It's all about choices and now you have several! 426 427P.S. Following the tradition set forth by the previous authors, I will 428remain anonymous for the time being. 429 430P.P.S. Sending my greetings and thanks to all the people who worked on this 431project before me and kept it alive over the years! 432 433--Unperson Hiro 43419 February 2013 435 436