Vanity Addresses for Onionspray

You are setting up an Onion site! And you want a vanity .onion address! Alright, so let's talk about how to do it for Onionspray.

Built-in support for vanity addresses

Onionspray comes with built-in support for vanity address generation since version 1.7.0 through Onionmine.

A working Onionspray installation can be used to mine Onion Addresses in two ways:

1. By using the %NEW_V3_VANITY_ONION_% placeholder in template files.
2. By manually invoking onionspray genkey-vanity <filter>.

Both are explained in the usage guide, and the rest of this document briefly deals with the best approaches to generate addresses, both in terms of hardware resources and third-party software.

Using Onionmine directly

Onionmine is a simple, handy and flexible tool for managing Onion Service keys and certificates.

Despite being bundled with Onionspray as explained above, Onionmine can be installed as a standalone program.

There are a number of ways to use it, and once you have your keys generated it's easy to export these to Onionspray.

Using other tools

Many other tools are available for mining vanity .onion addresses, such as using the mkp224o program directly.

Performance and tuning tips

Check Onionmine's tuning page for performance tips when mining .onion keys.

Installing .onion addresses in Onionspray

After generating keys, the next step is copying them to the Onionspray installation.

When using the built-in key generator

If you have used the built-in vanity generator, there's nothing else to be done: the generated keys are already installed at Onionspray's secrets folder.

When using Onionmine as a standalone tool

If you have used Onionmine as a standalone tool to generate your .onion keys, you can easily export these to Onionspray.

When using other tools

Tools like mkp224o save the keys they generate as three separate files: hs_ed25519_public_key, hs_ed25519_secret_key, and hostname; this is elegant but hard to manipulate, so Onionspray creates its own standard for storing v3 onion addresses in the secrets folder.

If you are in a directory which contains the above-named three files, you can run a helper shellscript by using a command, something like:

./onionspray/lib/rename-v3-keys-for-onionspray-secrets.sh

... which will safely create TWO files:

• someverylongonionaddressinvolvingalotofbase32characterss.v3pub.key
• someverylongonionaddressinvolvingalotofbase32characterss.v3sec.key

... that can be moved into your ~/onionspray/secrets/ folder, for Onionspray to use when you run onionspray config ....

Make sure to test the keys

Regardless of the tool you used to generate your keys, please test first with a tor implementation before putting it on production, to ensure it will work and is accepted by the tor daemon.

If you mine Onion Addresses, beware, and always test them thoroughly on Onionspray, especially before buying TLS Certificates which cites them.

Check that it matches your expectation, and if not, discard that vanity address and start over.