Verified Commit e59d1e00 authored by Silvio Rhatto's avatar Silvio Rhatto
Browse files

Feat(docs): README: vanity addresses explanation

parent bc40990d
......@@ -5,6 +5,69 @@ creation based on the [mkp224o generator](https://github.com/cathugger/mkp224o).
Useful when one is generating vanity .onions for many sites.
## But what are Vanity Addresses?
"Vanity" .onion addresses are a partial workaround on the difficulty to
memorize the 56-char long [Onion Service](https://community.torproject.org/onion-services/)
addresses.
A vanity address is an .onion that starts with a pre-chosen number of
characters, usually a meaningful name related to an specific Onion
Service.
For instance, one might try to generate an .onion address for the
`mysitename` website and end up with something looking like this:
mysitenameyx4fi3l6x2gyzmtmgxjyqyorj9qsb5r543izcwymle.onion
This has some advantages:
* It's easy for Onion Service Users to know about which site they're
about to access.
* It has some branding appeal to site owners.
* It's easy for Onion Service Operators to debug their logs and know
which site has errors without recurring to a table or to memorize
some random characters from a regular .onion address as
[pointed by Alec Muffet](https://github.com/alecmuffett/eotk/blob/master/docs.d/TIPS-FOR-MINING-ONIONS.md).
But also has some disadvantages:
* It's relatively easy for anybody having average computing resources
to create other keys beginning with `mysitename` (although it's very,
very unlikely to come up with the exactly key from the example above).
So, in a sense, vanity keys might be confusing and offer a false sense
of identity: users can easily mistaken into accessing an impersonating
.onion service just because it starts with `mysitename`.
* It consumes resources (time and energy): the bigger the vanity name,
the longer (and more computing power) it takes.
It seems like [The Tor Project](https://www.torproject.org)
does not have an official recommendation about using vanity addresses or not,
but the Onion Services v3 spec (see References below) some concerns.
An argument for using it, despite the resource consumption, is that an
attacker wishing to impersonate an existing .onion site by creating a
fake version of it might be inclined to use vanity addresses as an
additional way to convince users that their address is the correct.
If the legitimate site does not use a vanity address, users might get
confused and think that the fake site is the valid one since it
has a nicer address!
The long term solution involves a better onion naming scheme, with
[existing proposals fort that](https://gitlab.torproject.org/tpo/onion-services/onion-support/-/wikis/Documentation/Onion-Services-UX-Proposals)
and that can make vanity addresses only as as way to help sysadmins to group
.onion addresses like when running many
[Onionbalance](https://onionbalance.readthedocs.io/en/latest/) backends.
While that does not happen, vanity address generation continues to be and
important [advanced
setting](https://community.torproject.org/onion-services/advanced/) to consider
when setting up Onion Services, and Onionmine aims to ease this process.
## Features
* Handy commands to create configuration and mine keys.
......@@ -112,12 +175,18 @@ for the current task list.
Other implementations than `mkp224o`:
* [GitHub - ciehanski/oniongen-hs: v3 onion vanity URL generator written in Haskell](https://github.com/ciehanski/oniongen-hs)
* [ciehanski/oniongen-hs: v3 onion vanity URL generator written in Haskell](https://github.com/ciehanski/oniongen-hs)
* [rdkr/oniongen-go: 🔑 v3 .onion vanity URL generator written in Go](https://github.com/rdkr/oniongen-go)
## References
* [Make Your Site Available Over Tor: Guide To EOTK, The Enterprise Onion Toolkit](https://shen.hong.io/making-websites-on-tor-using-eotk/)
* [eotk/TIPS-FOR-MINING-ONIONS.md at master · alecmuffett/eotk](https://github.com/alecmuffett/eotk/blob/master/docs.d/TIPS-FOR-MINING-ONIONS.md)
* 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.
* [mkp224o/OPTIMISATION.txt at master · cathugger/mkp224o](https://github.com/cathugger/mkp224o/blob/master/OPTIMISATION.txt)
* The `[VANITY]` section at the [Tor Rendezvous Specification - Version 3](https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/rend-spec-v3.txt)
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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment