README.md 9.24 KB
Newer Older
Silvio Rhatto's avatar
Silvio Rhatto committed
1
# Onionmine: Onion Services keys and TLS certs generator
2

3
Onionmine is a handy wrapper to:
4

5
6
7
* Organize the so-called [vanity address][] creation based on the [mkp224o
  generator][].
* Help the TLS certificate generation for Onion Services.
8

9
It's useful when one is generating many Onion Services in a row.
10

11
12
[vanity address]: https://community.torproject.org/onion-services/advanced/vanity-addresses/
[mkp224o generator]: https://github.com/cathugger/mkp224o
13

Silvio Rhatto's avatar
Silvio Rhatto committed
14
## Features
15

Silvio Rhatto's avatar
Silvio Rhatto committed
16
17
18
* Handy commands to create configuration and mine keys.
* Can be integrated with an external password manager
  to store the random seed.
19

Silvio Rhatto's avatar
Silvio Rhatto committed
20
## Usage
21

22
23
24
25
### Getting

Get Onionmine with it's submodules using

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

Silvio Rhatto's avatar
Silvio Rhatto committed
28
### Configuring
29

30
31
32
Onionmine uses an `onionmine.conf` file to set it's main configuration,
including `mkp224o` build and invocation flags. Onionmine provides a [sample
configuration][] with lots of examples:
33

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

36
37
[sample configuration]: onionmine.conf.sample

38
### Provisioning
39

40
The following command installs the needed dependencies on an Debian-compatible
41
system and compiles `mkp224o` (requires `sudo` privileges):
42

43
    ./onionmine provision
44

45
46
You might run it on a dedicated enviroment, such as an Raspberry Pi mini-server
or a dedicated virtual machine.
Silvio Rhatto's avatar
Silvio Rhatto committed
47

48
49
Currently testes only on [Debian GNU/Linux](https://www.debian.org).

Silvio Rhatto's avatar
Silvio Rhatto committed
50
### Mining
51

Silvio Rhatto's avatar
Silvio Rhatto committed
52
Create a configuration, use your favourite `$EDITOR` to create filters
53
54
and start mining!

55
    ./onionmine config my-pool            # create a config called "my-pool"
Silvio Rhatto's avatar
Silvio Rhatto committed
56
    $EDITOR     pools/my-pool/filters.lst # populate your filters
57
    ./onionmine mine my-pool              # start mining
58

59
60
61
This command takes care of compiling `mkp224o` and start mining with the
desired configuration.

62
63
64
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`.
65

66
67
Check [this configuration](pools/example.org) for an example mining pool.

68
69
70
### Per-pool environment override

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

74
75
### Recompiling

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

80
    ./onionmine compile
81

82
### Stopping and resuming
83

84
The [onionmine.conf.sample](onionmine.conf.sample) commes with examples to
85
handle the `mkp224o` seed passphrase option to be used along the `--checkpoint`
86
parameter if you plan to stop/resume the search.
87

88
89
90
91
92
93
94
95
96
97
98
99
100
101
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
102
103
104
105
106
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.

107
That means that passphrases should:
108

109
110
111
* 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.
112

113
114
115
116
117
118
119
120
121
122
123
124
125
### Onionbalance compatibility

When generating keys for [Onionbalance](https://onionbalance.readthedocs.io/en/latest/),
make sure to use one pool per key:

1. One pool for the frontend instance.
2. 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.

126
127
128
129
130
### Testing your candidate keypairs

Once you selected 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.

131
132
133
Onionmine provides a test script for that:

    ./onionmine test-keys
134
135
136
137
138

Check [this
issue](https://gitlab.torproject.org/tpo/onion-services/onionmine/-/issues/2)
to see how it works.

139
### Selecting a candidate
Silvio Rhatto's avatar
Silvio Rhatto committed
140

141
142
It's possible to indicate that a candidate is selected by running the
`selected-candidate` sub-command like this:
Silvio Rhatto's avatar
Silvio Rhatto committed
143

144
    ./onionmine select-candidate example.org test35n4rit2dzagyzixi7kfktuzns3q464donfggtn5jhflqvwihrqd.onion
Silvio Rhatto's avatar
Silvio Rhatto committed
145

146
147
This only creates a symbolic link in the pool folder to make easy to know which
candidate is currently selected.
Silvio Rhatto's avatar
Silvio Rhatto committed
148

149
### HTTPS certificates compatibility
Silvio Rhatto's avatar
Silvio Rhatto committed
150

151
152
Onionmine ships with [onion-csr][] as a submodule to ease the creation of
certificates for HTTPS usage with a selected candidate from a given pool.
Silvio Rhatto's avatar
Silvio Rhatto committed
153

154
The [provisioning](bin/provision) procedure also makes sure that this software is compiled.
155

156
It can be invoked by running
157

158
    ./onionmine onion-csr <pool> <nounce>
159

160
[onion-csr]: https://github.com/HARICA-official/onion-csr
161

Silvio Rhatto's avatar
Silvio Rhatto committed
162
### Encrypting selected keys to an external keystore
163

Silvio Rhatto's avatar
Silvio Rhatto committed
164
It's possible to encrypt the selecte keys to an external keystore of your choice,
165
166
167
168
169
170
171
172
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.

Silvio Rhatto's avatar
Silvio Rhatto committed
173
174
175
176
177
178
179
180
181
182
183
### 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>

Silvio Rhatto's avatar
Silvio Rhatto committed
184
### Remote mining
185
186
187
188
189
190
191
192
193
194
195

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.

196
197
198
199
### Batch operations

Some operations have a batch mode, like this:

200
    ./onionmine test-keys-batch <batch_name|all>
201

202
203
Batches reside at the `batches/<batch_name>` folders with
the following files there:
204
205
206
207
208
209
210
211

* `batch.conf`: an optional file to allow configuration parameter
  from `onionmine.conf` to be overriden.

* `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.

212
213
214
215
216
217
218
219
* 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.
220

221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
### 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.

239
## Tasks
240

241
Check the [issue queue](https://gitlab.torproject.org/tpo/onion-services/onionmine/-/issues)
242
for the current task list.
243

Silvio Rhatto's avatar
Silvio Rhatto committed
244
## Alternatives
245

Silvio Rhatto's avatar
Silvio Rhatto committed
246
Other implementations than `mkp224o`:
247

248
* [ciehanski/oniongen-hs: v3 onion vanity URL generator written in Haskell](https://github.com/ciehanski/oniongen-hs)
Silvio Rhatto's avatar
Silvio Rhatto committed
249
* [rdkr/oniongen-go: 🔑 v3 .onion vanity URL generator written in Go](https://github.com/rdkr/oniongen-go)
250

Silvio Rhatto's avatar
Silvio Rhatto committed
251
## References
252

253
254
255
256
* The guide [Make Your Site Available Over Tor: Guide To EOTK, The Enterprise Onion Toolkit](https://shen.hong.io/making-websites-on-tor-using-eotk/)
  has a detailed discussion about how to mine keys using `mkp224o`.
* [eotk/TIPS-FOR-MINING-ONIONS.md](https://github.com/alecmuffett/eotk/blob/master/docs.d/TIPS-FOR-MINING-ONIONS.md)
  contains important advice.
Silvio Rhatto's avatar
Silvio Rhatto committed
257
* [mkp224o/OPTIMISATION.txt at master · cathugger/mkp224o](https://github.com/cathugger/mkp224o/blob/master/OPTIMISATION.txt)
258
259
260
261
262
  details the optimization flags of `mkp224o`.
* The `[VANITY]` and `[VANITY-REFS]` sections from the
  [Tor Rendezvous Specification - Version 3](https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/rend-spec-v3.txt)
* The Part three of [Facebook, hidden services, and https certs | The Tor Project](https://blog.torproject.org/facebook-hidden-services-and-https-certs/) has
  and interesting discussion brute forcing the .onion keyspace.