Onionmine usage¶

This document assumes you have a working Onionmine installation.

Configuring¶

Optional step

This is an optional step for additional customization. Onionmine already comes with reasonable defaults.

Onionmine uses an onionmine.conf file to set it's main configuration, including vendorized dependencies' build and invocation flags. Onionmine provides a sample configuration with lots of examples:

cp onionmine.conf.sample onionmine.conf # edit to customize

Quick generation¶

As detailed in the tutorial the quickest way to generate a vanity address is using the generate command:

onionmine generate <chars>

Where <chars> is a Base32-valid character sequence representing the starting letters/numbers of the generated .onion address.

This operation is resource-intensive, so try to avoid asking for a sequence longer than 6 chars.

Mining¶

To start mining Onion Services address in bulk, create a mining pool and use your favourite $EDITOR to create filters and start mining!

First, configure a new pool:

onionmine config my-pool # create a config called "my-pool"

Then, add a filter to the pool configuration, for the mining operation:

onionmine add-filter my-pool myfilter

A filter can be any Base32-encodable in the range of 1 to 8 characters (more than that will take a long time, require a lot of computation and energy to generate).

The filter configuration can also be edited, with one filter per line:

onionmine edit my-pool

Filter size

We recommend a filter size no longer than 6 characters.

Example filters:

mypool
pool

For additional help on mining filters, check the mkp224o documentation (this is the underlying program that does the actual mining).

Finally, start the mining operation:

onionmine mine my-pool # start mining

This command takes care of compiling mkp224o and start mining with the desired configuration.

Run the above onionmine config command for each Onion Service you're mining keys. Configuration and mined keys are stored under the pool/my-pool folder, with mined keys at the pool/my-pool/candidates.

Check this configuration for an example mining pool.

Per-pool environment override¶

Custom environment overrides are possible. For the my-pool config, place any overrides at the pools/my-pool/pool.conf or pools/my-pool/local.conf file, which are parsed after the default onionmine.conf folder.

Recompiling¶

If by any change a mkp224o recompilation is needed without triggering additional key generation, use this command (e.g. after you change it's build flags at the onionmine.conf file):

onionmine compile

Stopping and resuming¶

The onionmine.conf.sample comes with examples to handle the mkp224o seed passphrase option to be used along the --checkpoint parameter if you plan to stop/resume the search.

Stopping can be done by interrupting the mining operation (like typing Ctrl C) and resuming happens once you re-start mining with the same parameters as previously.

If you get this error:

ERROR: could not create directory for key output

That's probably because you're resuming a previous mining for a given pool and mkp224o tried to create a folder for a keypair candidate that already exists. Just let mkp224o continue to run and in a while you should get new keys again.

Please note the security implications of this feature. As mkp224o outputs when using -P:

CAUTION: avoid using keys generated with same password for unrelated services, as single leaked key may help attacker to regenerate related keys.

That means that passphrases should:

Not be reused for different services.
Either be destroyed along unused candidates OR, if stored, have the same storage security level than the .onion keypair.

Onionbalance compatibility¶

When generating keys for Onionbalance, make sure to use one pool per key:

One pool for the frontend instance.
One pool per backend instance.

This is for security considerations: keys generated within the same pool are highly correlated. This means that if an attacker takes control of a backend instance that uses a keypair generated in the same pool, then the attacker can try to regenerate related keys.

Testing your candidate keypairs¶

Once (or before) you select a candidate address that suits your needs, you might want to test if the keys are validated by the Tor process, just to make sure.

Onionmine provides a test script for that:

onionmine test-candidate

Check this issue to see how it works.

Selecting a candidate¶

A mined candidate can be selected with the select-candidate command.

Passing no arguments to the select-candidate command will display all available candidates:

onionmine select-candidate example.org
usage: onionmine select-candidate <pool> <candidate>

Select a keypair among candidates from a mining pool:

    pool:      the mining pool to operate on
    candidate: which candidate in the pool to test

Available candidates in pool example.net:

    0. test35n4rit2dzagyzixi7kfktuzns3q464donfggtn5jhflqvwihrqd.onion

Configured mining filters:

    ^(examp|ample|test)
    sample

It's possible to indicate that a candidate is selected by running the selected-candidate sub-command like this:

onionmine select-candidate example.org test35n4rit2dzagyzixi7kfktuzns3q464donfggtn5jhflqvwihrqd.onion

This only creates a symbolic link in the pool folder to make easy to know which candidate is currently selected.

You can also select by passing the candidate number instead of it's full address:

onionmine select-candidate example.org 0

HTTPS certificates¶

Onionmine can generate self-signed X.509 certificates for TLS/HTTP, ready to be used in web services and other applications, as well as a Certificate Request to be sent to a Certificate Authority in order to get a CA-validated certificate. All that in a single command:

onionmine generate-select-cert <pool>

Onionmine can also generate a second Certificate Request with a proof of ownership for the .onion address, which is needed by the CA-based certification process:

It can be invoked by running

onionmine onion-csr <pool> <nonce>

where the <nonce> is a string provided by the Certification Authority during the certification process.

This command above uses the onion-csr application under the hood.

Once a CA-issued certificate is available, save it under pools/<pool>/certs/selected/ca-signed.crt, so it can be exported to external applications directly from Onionmine.

Exporting to Onionspray¶

Onionmine can export selected keys and certificates to a local or remote Onionspray installation:

onionmine export-to-onionspray <pool> <onionspray-path> <onionspray-project>

Example:

onionmine export-to-onionspray example.net remoteserver:/home/onionspray/onionspray example.net

Encrypting selected keys to an external keystore¶

It's possible to encrypt the selected keys to an external keystore of your choice, by using the following command:

onionmine encrypt-selected-key <pool>

It only needs that you setup a custom encryption command using the ENCRYPTION_COMMAND param at your onionmine.conf. Check the sample configuration for details.

Decrypting selected keys from an external keystore¶

Similarly, an decryption command is provided for Onion Service keys, restoring then from a keystore to the mining pool:

onionmine decrypt-key <pool> <onion-address>

Certificates for selected keys can also be decrypted easily:

onionmine decrypt-selected-cert <pool> <onion-address>

Generating random addresses¶

A standard, random .onion address can be generated with

onionmine generate-random-onion-v3-c-tor <pool>

Remote mining¶

Onionmine provides two helper subcommands to sync between local and remote hosts:

onionmine sync-to-remotes   # syncs both the codebase and the pools to remote hosts
onionmine sync-from-remotes # syncs only the pools from remote hosts

Remote hosts and base folder can be set using the onionmine.conf config file, as well as other parameters such as rsync options and exclusion patterns.

This allows remote mining operations, like in a server farm.

Batch operations¶

Some operations have a batch mode, like this:

onionmine test-keys-batch <batch_name|all>

Batches reside at the batches/<batch_name> folders with the following files there:

batch.conf: an optional file to allow configuration parameter from onionmine.conf to be overridden.
batch.list: the list of actions to be performed: each line can contain only the pool name or also space-separated options for each invocation.
A per-operation folder, like batches/<batch_name>/test-keys, hosting operation data such as:
status: tracks the latest status of a given batch.
processed: stores all the processed tasks in an operation.

To run a batch for all the pools, use the all special batch name, corresponding to the batches/all folder. In this case, batch.list and batch.conf are ignored.

Wiping secrets and pools¶

Once you have deployed the service (or at least have all keys storage in an encrypted long-term storage), you can wipe the pool secrets using this command:

onionmine wipe-pool-secrets <domain>

The command above only removes secret material such as private keys, passphrases and revocation codes.

If you want to permanently delete the whole mining pool, including non-private material such as public keys, use this command instead:

onionmine wipe-pool <domain>

In any case, make sure first to encrypt selected material in a long-term encrypted keystore.

Optionally, you can pass a --force option so wipe-pool won't ask for confirmation:

onionmine wipe-pool <domain> --force

Irreversible operation

Wiping a pool is an irreversible operation. You'll irrevocably lose all keys and certificates in the pool. Be careful when using this option, and make encrypted and tested backups of the data you want to save.

Other commands¶

For the full list of available commands, type

onionmine