Onionmine tutorial¶

This tutorial page shows how Onionmine can quickly generate a vanity address for Onion Services, and related TLS/HTTPS certificate, step-by-step:

Choose a way to run Onionmine:
- Using a container image.
- Running directly from the source code.
Try it out:
- Generating a vanity .onion address.
- Generating a self-signed certificate.
- Generating certificate requests for a CA-signed certificate.
- Generating a random .onion address.

System requirements

Running Onionmine requires a GNU/Linux-like system and some knowledge of command line.

Choose a way to run Onionmine¶

Running from a container image¶

The easiest way to generate a vanity address is running Onionmine's container with a runtime like Docker or Podman with one of the official images (in the command below, change docker to podman if you're using Podman):

docker pull containers.torproject.org/tpo/onion-services/onionmine/onionmine

Then create a pool folder for key mining, which will be mounted inside the container:

mkdir -p pools

Finally, let's make an alias to invoke Onionmine (if you're using Podman instead of Docker, change docker to podman in the following command):

alias onionmine="docker run -it --mount type=bind,src=`pwd`/pools,target=/app/onionmine/pools onionmine"

If you want, adapt this this alias and add it in your command line profile, so this command become always available.

Now you should have a working Onionmine installation! Just type onionmine to run it:

onionmine

If you don't get Onionmine's output, check again your installation.

Running from source¶

Another option is to run Onionmine directly from the source code.

1. Get the Onionmine source code¶

Clone the repository recursively using Git:

git clone --recursive https://gitlab.torproject.org/tpo/onion-services/onionmine.git

Go to the repository working copy:

cd onionmine

2. Install dependencies¶

The system-wide dependencies can be installed with

./onionmine install-dependencies

This step requires sudo, an currently (as of 2025-03) only works for Debian-like systems.

3. Create an alias¶

Finally, create and alias to run Onionmine from the cloned repository:

alias onionmine="`pwd`/onionmine"

If you want, adapt this this alias and add it in your command line profile, so this command become always available.

Now you should have a working Onionmine installation! Just type onionmine to run it:

onionmine

If you don't get Onionmine's output, check again your installation.

Trying it out¶

Generating a vanity address¶

Now that you have a working Onionmine installation, ask it to generate a customized .onion address starting with a specific character sequence (such as test) with the following command:

onionmine generate test

This will generate an .onion address starting with the string test, as the output of the command above shows with Onionmine 1.1.0:

config: ensuring that /app/onionmine/pools/test/filters.lst exists...
generate: configuring pool test...
mine: starting mkp224o...
set workdir: /app/onionmine/pools/test/candidates/
sorting filters... done.
filters:
        test
in total, 1 filter
using 4 threads
testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion
>calc/sec:960197.913134, succ/sec:9.975460, rest/sec:49.877302, elapsed:0.100246sec
waiting for threads to finish... done.
Current selected candidate for the test pool:

    testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion

generate: keys for "test" saved at /app/onionmine/pools/test/candidates/testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion

The resulting keys will be inside your "pools" folder, specifically these files at pools/test/candidates/testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion:

hostname: contains the .onion address hostname, in this case testrlzkzon6eiof3lgymq6bllncbg3mzc4rwn6jhgseshli5jbw6xyd.onion.
hs_ed25519_public_key: the public key, in C Tor's format.
hs_ed25519_secret_key: the private key, in C Tor's format.

Your vanity address is now ready to be included in your Tor daemon configuration!

Expensive operation for large sequences

Vanity address generation can take a long time and consume a lot of resources as the desired text sequence grow larger.

The recommendation is to try a combination around 6 characters or less.

Generating a self-signed TLS/HTTPS certificate¶

If you plan to use your new Onion Service with HTTPS or other protocol relying on TLS, use this to create the secret key and a self-signed certificate:

onionmine generate-selected-cert test

Output (as in Onionmine 1.1.0):

Generating the keypair and the CSR...
-----
read EC key
writing EC key
Generating a self-signed certificate...

This is the self-signed certificate:
------------------------------------

-----BEGIN CERTIFICATE-----
MIICtzCCAjygAwIBAgIUBLjUwWoD5ghgdj8FeNL2QpLcxyAwCgYIKoZIzj0EAwMw
STFHMEUGA1UEAww+dGVzdGhvd2VuN254ZHVzcW5jc25zMnlpM2Zqcmp3cXM0dmt3
N21vYnJlNGFnZWVqZW5vZHJlYWQub25pb24wHhcNMjUwMzI1MTcwNjAxWhcNMjYw
MzI1MTcwNjAxWjBJMUcwRQYDVQQDDD50ZXN0aG93ZW43bnhkdXNxbmNzbnMyeWkz
ZmpyandxczR2a3c3bW9icmU0YWdlZWplbm9kcmVhZC5vbmlvbjB2MBAGByqGSM49
AgEGBSuBBAAiA2IABDQZxBXBn/2vbeiitYSCPDMSEtfZEgYdKRwB4MZ8+TLD8kUC
VVzAe6Av5oaPFNJNM6HA8FHAP/7aFbe2oSrZOwUDokBZstmeCqqa2H/+z3bqeE6Z
gcFXNWNJuMJIy3WZDaOB5DCB4TAdBgNVHQ4EFgQUZi+dQ3M7ucvwB5tC9x7uUxOm
SRkwHwYDVR0jBBgwFoAUZi+dQ3M7ucvwB5tC9x7uUxOmSRkwDwYDVR0TAQH/BAUw
AwEB/zCBjQYDVR0RBIGFMIGCgj50ZXN0aG93ZW43bnhkdXNxbmNzbnMyeWkzZmpy
andxczR2a3c3bW9icmU0YWdlZWplbm9kcmVhZC5vbmlvboJAKi50ZXN0aG93ZW43
bnhkdXNxbmNzbnMyeWkzZmpyandxczR2a3c3bW9icmU0YWdlZWplbm9kcmVhZC5v
bmlvbjAKBggqhkjOPQQDAwNpADBmAjEAk4R0w7gtl8FfDi9M0OQVDjdtEeZCvVNd
Rt6SpW8gRBUNSi2i+TlNsYNlgWWIKjIGAjEA3yVlwDBcHPFwhHt5fsjqDfZvQWni
evWoo4CD2Q8KLEVzNqg/k1PUy4kyzYfWdqcN
-----END CERTIFICATE-----

Self-signed certificate information:
------------------------------------

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            04:b8:d4:c1:6a:03:e6:08:60:76:3f:05:78:d2:f6:42:92:dc:c7:20
        Signature Algorithm: ecdsa-with-SHA384
        Issuer: CN=testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion
        Validity
            Not Before: Mar 25 17:06:01 2025 GMT
            Not After : Mar 25 17:06:01 2026 GMT
        Subject: CN=testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (384 bit)
                pub:
                    04:34:19:c4:15:c1:9f:fd:af:6d:e8:a2:b5:84:82:
                    3c:33:12:12:d7:d9:12:06:1d:29:1c:01:e0:c6:7c:
                    f9:32:c3:f2:45:02:55:5c:c0:7b:a0:2f:e6:86:8f:
                    14:d2:4d:33:a1:c0:f0:51:c0:3f:fe:da:15:b7:b6:
                    a1:2a:d9:3b:05:03:a2:40:59:b2:d9:9e:0a:aa:9a:
                    d8:7f:fe:cf:76:ea:78:4e:99:81:c1:57:35:63:49:
                    b8:c2:48:cb:75:99:0d
                ASN1 OID: secp384r1
                NIST CURVE: P-384
        X509v3 extensions:
            X509v3 Subject Key Identifier:
                66:2F:9D:43:73:3B:B9:CB:F0:07:9B:42:F7:1E:EE:53:13:A6:49:19
            X509v3 Authority Key Identifier:
                66:2F:9D:43:73:3B:B9:CB:F0:07:9B:42:F7:1E:EE:53:13:A6:49:19
            X509v3 Basic Constraints: critical
                CA:TRUE
            X509v3 Subject Alternative Name:
                DNS:testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion, DNS:*.testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion
    Signature Algorithm: ecdsa-with-SHA384
    Signature Value:
        30:66:02:31:00:93:84:74:c3:b8:2d:97:c1:5f:0e:2f:4c:d0:
        e4:15:0e:37:6d:11:e6:42:bd:53:5d:46:de:92:a5:6f:20:44:
        15:0d:4a:2d:a2:f9:39:4d:b1:83:65:81:65:88:2a:32:06:02:
        31:00:df:25:65:c0:30:5c:1c:f1:70:84:7b:79:7e:c8:ea:0d:
        f6:6f:41:69:e2:7a:f5:a8:a3:80:83:d9:0f:0a:2c:45:73:36:
        a8:3f:93:53:d4:cb:89:32:cd:87:d6:76:a7:0d

This is the certificate request to be sent to a Certificate Authority:
----------------------------------------------------------------------

-----BEGIN CERTIFICATE REQUEST-----
MIIBQTCByAIBADBJMUcwRQYDVQQDDD50ZXN0aG93ZW43bnhkdXNxbmNzbnMyeWkz
ZmpyandxczR2a3c3bW9icmU0YWdlZWplbm9kcmVhZC5vbmlvbjB2MBAGByqGSM49
AgEGBSuBBAAiA2IABDQZxBXBn/2vbeiitYSCPDMSEtfZEgYdKRwB4MZ8+TLD8kUC
VVzAe6Av5oaPFNJNM6HA8FHAP/7aFbe2oSrZOwUDokBZstmeCqqa2H/+z3bqeE6Z
gcFXNWNJuMJIy3WZDaAAMAoGCCqGSM49BAMDA2gAMGUCMQCqHxhP23lngAmObVRI
8Vpa3s+T7lqFToEz8S74BbDDOWnM3IhcWg87fC9ObcMDjqoCMAGHpP+Ds+BorT53
pGbAYNmVhm7tac2zbL5eQsgdfGS0hbFUzwwYUhW/6XSkUamYjg==
-----END CERTIFICATE REQUEST-----

Certificate Request information:
--------------------------------

Certificate Request:
    Data:
        Version: 1 (0x0)
        Subject: CN=testhowen7nxdusqncsns2yi3fjrjwqs4vkw7mobre4ageejenodread.onion
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (384 bit)
                pub:
                    04:34:19:c4:15:c1:9f:fd:af:6d:e8:a2:b5:84:82:
                    3c:33:12:12:d7:d9:12:06:1d:29:1c:01:e0:c6:7c:
                    f9:32:c3:f2:45:02:55:5c:c0:7b:a0:2f:e6:86:8f:
                    14:d2:4d:33:a1:c0:f0:51:c0:3f:fe:da:15:b7:b6:
                    a1:2a:d9:3b:05:03:a2:40:59:b2:d9:9e:0a:aa:9a:
                    d8:7f:fe:cf:76:ea:78:4e:99:81:c1:57:35:63:49:
                    b8:c2:48:cb:75:99:0d
                ASN1 OID: secp384r1
                NIST CURVE: P-384
        Attributes:
            (none)
            Requested Extensions:
    Signature Algorithm: ecdsa-with-SHA384
    Signature Value:
        30:65:02:31:00:aa:1f:18:4f:db:79:67:80:09:8e:6d:54:48:
        f1:5a:5a:de:cf:93:ee:5a:85:4e:81:33:f1:2e:f8:05:b0:c3:
        39:69:cc:dc:88:5c:5a:0f:3b:7c:2f:4e:6d:c3:03:8e:aa:02:
        30:01:87:a4:ff:83:b3:e0:68:ad:3e:77:a4:66:c0:60:d9:95:
        86:6e:ed:69:cd:b3:6c:be:5e:42:c8:1d:7c:64:b4:85:b1:54:
        cf:0c:18:52:15:bf:e9:74:a4:51:a9:98:8e

Summary:
--------

All files stored at /app/onionmine/pools/test/certs/selected:

* privatekey.pem: the private key, stored encrypted, not to be shared.
* passphrase: the passphrase to decrypt the encrypted private key, not to be shared.
* key.pem: the privatekey, decrypted; should be kept private.
* self-signed.crt: the self-signed certificate, which can be made public.
* csr.pem: the certificate request file, to be optionally sent
  to a Certificate Authority.

The resulting key and certificate request will be available at the pools/test/certs/selected/.

These files (especially the decrypted private key and the self-signed certificate) are ready to be used by your service's endpoints, like HTTP servers such a Apache, NGINX etc.

Generating certificate requests for a CA-signed certificate¶

In order to get a CA-validated certificate, Onionmine can generate an additional Certificate Request which can be submitted to a Certificate Authority in order to prove ownership of an .onion service address:

onionmine onion-csr test 0123456789012345678901234567890123456789

This command is a wrapper around the onion-csr application, and the big string 0123456789012345678901234567890123456789 is a cryptographic nonce provided by the CA during the certificate request procedure.

Generating a random .onion address¶

But what if you just want to generate a random .onion address in advance?

That can be achieved with:

mkdir pools/myrandom
onionmine generate-random-onion-v3-c-tor myrandom

Output (as of Onionmine 1.1.0):

Generating a random .onion v3 address using C Tor on pool myrandom...
Generated adddress:
4mqlp6nvjnu5qclinb6vev4lqohw2qeieggogiutpw55dnnes7cyp5id.onion