doc/DirauthEd25519Keys.md

+= Directory Authority Ed25519 Keys =
+
+If you want to know how to generate or renew keys, see [[GeneratingDirauthKeys]].
+
+== Legacy RSA Keys ==
+
+So far, Tor relays always had an identity key that got auto-created when first
+configuring Tor as a relay and was stored in the 'keys' directory inside Tor's
+data directory, in a file called 'secret_id_key'. This key is the sole thing
+that describes a relay's identity. This key is stored online in Tor's data
+directory, so a compromise of the host implies a compromise of the relay
+identity, and thus the relay. Once the host is cleaned, a new identity key has
+to be created. In this regard, directory authorities are just like regular
+relays. They have identity keys which get stored online, and if the host is
+compromised they have to be replaced. The difference to relays is that we
+actually include the dirauths' keys in Tor's source code. This has led to a
+situation where we had to implement support for legacy keys for older clients
+with older Tor versions.
+
+Separate to the relay identity key, dirauths also have another key, the
+authority identity key. This key is supposed to be stored offline and specially
+protected. Using this key, the dirauth operator regularly signs a temporary key
+that is used to sign the consensus. Just like the relay identity key, the
+authority identity key is referenced inside Tor to ensure that clients have a
+way to verify a consensus they received. To deal with everything involved, the
+"tor-gencert" tool exists which aids in both creating the initial version of
+the authority identity key, stored in a file authority_identity_key, as well as
+the authority_signing_key file and the corresponding certificate, stored in
+authority_certificate. authority_signing_key and authority_certificate have to
+be stored online, and updated before they expire.
+
+You probably knew all of this so far (except for the stuff I got wrong, you
+probably knew better). Sorry for being boring. The exciting part is that none
+of the above changes at all, for now. But here's the new stuff!
+
+== New Ed25519 Keys ==
+
+Because RSA 1024 is really sucky nowadays, we're moving to ed25519-backed relay
+identity keys. As an added bonus, the key can optionally be stored offline (not
+so optional if you're a dirauth, I'd say). More on offline storage in a bit.
+This move to new identity keys is a really slow one, but the 0.2.7.x release
+series is the first to include support for the new keys. So from now on and for
+a (long) while yet, Tor relays will have two identity keys - one rsa, one
+ed25519.
+
+Concretely, the ed25519 equivalent of the old secret_id_key file are actually
+these four files:
+ - ed25519_master_id_secret_key (can be stored offline)
+ - ed25519_master_id_public_key (online)
+ - ed25519_signing_secret_key (online, re-created occasionally)
+ - ed25519_signing_cert (online, re-created occasionally)
+
+The 'ed25519_master_id_secret_key' file stores a relay's ed25519 identity.
+Once that is "linked" to a relay's RSA identity key (by starting a relay using
+them), they should remain linked forever. If one is to be replaced, the other
+should be replaced as well. After all, there's still just one relay identity
+which is supposed to be backed by both. The dirauths have support for enforcing
+this behaviour. In the event that a dirauth should lose its RSA key, we would
+either have to change its ed25519 key, too - or manually update our mapping
+file to fix the issue. But I think we can wait until that's required.
+
+But this is where several issues cropped up. The first issue stems from the
+fact that most relay ops probably don't want to remember to regularly replace
+their temporary identity key, and we don't want to make upgrading to 0.2.7.x a
+major hassle for all these people. That means when you first start a relay with
+a new version of Tor, all four ed25519 files are created on the fly on the
+online host, and immediately published to the dirauths. The chance to keep the
+master key offline is lost. To combat this issue, dirauths currently are not
+enforcing the rule that relays have to link their keys permanently and treat
+the RSA key as the "real" identity. This has led the second issue, bug #17668.
+Assuming my analysis is correct, this bug happens when the RSA key for a relay
+is replaced without replacing the ed25519 key. Tor - because it still treats
+the RSA key as the canonical identity for a relay - includes both relay
+descriptors in its vote, then fails to validate the vote it created because the
+ed25519 key is duplicated. So far, this duplication can be seen for IP:Port
+combinations in dirauth votes already - but having two relays on the same
+IP:Port is not treated as an error by Tor's vote parsing code, so the bug was
+never uncovered.
+
+== Offline Ed25519 Keys ==
+
+Back to the first issue, to make sure your relay never accidentally creates an
+ed25519 key online, the config option 'OfflineMasterKey 1' can be set. If Tor
+is then started without a usable key present, it won't create one but rather
+exit with an error. Please set that config option on your dirauths when you
+take them down for the upgrade (the 0.2.6.x release series doesn't understand
+the config option, unfortunately).
+
+Unfortunately, the offline workflow to deal with the ed25519 relay identity key
+is quite different from the authority identity key. tor-gencert does not know
+anything about ed25519 keys. Instead, to create the offline key for the first
+time, use
+	tor --keygen --DataDirectory <DIR> --SigningKeyLifetime "30 days"
+
+Tor will then place the four ed25519 files inside <DIR>/keys/. From there, copy
+the three online files ('ed25519_master_id_public_key',
+'ed25519_signing_secret_key', 'ed25519_signing_cert') to your dirauth's keys
+directory, just like you would with the tor-gencert generated files. Make sure
+not to copy ed25519_master_id_secret_key!
+
+The default lifetime for the online keys is 30 days, it's probably smart to
+sync this up with the lifetime of your authority identity key so you don't have
+to do a key dance twice.
+
+Assuming I forgot nothing, that should be it.