Feat(docs): README: vanity addresses explanation

README.md

@@ -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.