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 (moved). 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

--SigningKeyLifetime "30 days"

Tor will then place the four ed25519 files inside

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