Opened 4 years ago

Closed 3 years ago

#17021 closed defect (fixed)

Update FAQ entry about identity keys to mention ed25519 keys.

Reported by: nickm Owned by: Sebastian
Priority: Medium Milestone: Tor: 0.2.8.x-final
Component: Webpages/Website Version:
Severity: Normal Keywords: ed25519, TorCoreTeam201509, 201512-deferred, TorCoreTeam201602
Cc: s7r, tyseom, sebastian Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Child Tickets

Change History (16)

comment:1 Changed 4 years ago by nickm

Component: TorWebsite
Owner: set to Sebastian

comment:2 Changed 4 years ago by s7r

Cc: s7r added

comment:3 Changed 4 years ago by s7r

Hello Sebastian,

A suggestion for the faq. Please edit if you think it doesn't read right - I speak better English than I write when it comes to explaining things. Wanted the text to be as simple as possible and make sense for almost anyone.

In the current FAQ I only found one question related to relay identity keys:

I want to upgrade/move my relay. How do I keep the same key?

I recommend replacing the answer with this:

When upgrading your Tor relay, or moving it on a different computer, the important part is to keep the same identity keys (stored in "keys/ed25519_master_id_secret_key" and "keys/secret_id_key" in your DataDirectory). It is important to keep backups of the identity keys so you can restore a relay in the future in case you need to re-install - this way the reputation of the relay won't be wasted.

This means that if you're upgrading your Tor relay and you keep the same torrc and the same DataDirectory, then the upgrade should just work and your relay will keep using the same key. If you need to pick a new DataDirectory, be sure to copy your old keys/ed25519_master_id_secret_key and keys/secret_id_key over.

*Note: As of Tor 0.2.7 we are using new generation identities for relays based on ed25519 elliptic curve cryptography. Eventually they will replace the old RSA identities, but that will happen in time, to ensure compatibility with older versions. Until then, each relay will have both an ed25519 identity (identity key file: keys/ed25519_master_id_secret_key) and a RSA identity (identity key file: keys/secret_id_key). You need to copy / backup both of them in order to restore your relay, change your DataDirectory or migrate the relay on a new computer.

And add a new question:
How do offline ed25519 identity keys work? What do I need to know?

This feature is optional, you don't need to use it unless you want to. If you want your relay to run unattended for longer time without having to manually do the medium term signing key renewal on regular basis, best to leave the master identity secret key in DataDirectory/keys, just make a backup in case you'll need to reinstall it.

As of Tor 0.2.7 offline ed25519 identity keys are supported. In simple words, it works like this:

  • there is a master ed25519 identity secret key file named "ed25519_master_id_secret_key". This is the most important one, so make sure you keep a backup in a secure place - the file is sensitive and should be protected. Tor could encrypt it for you if you generate it manually and enter a password when asked.
  • a medium term signing key named "ed25519_signing_secret_key" is generated for Tor to use. Also, a certificate is generated named "ed25519_signing_cert" which is signed by the master identity secret key and confirms that the medium term signing key is valid for a certain period of time. The default validity is 30 days, but this can be customized by setting "SigningKeyLifetime N days|weeks|months" in torrc.
  • there is also a master public key named "ed25519_master_id_public_key, which is the actual identity of the relay advertised in the network. This one is not sensitive and can be easily computed from "ed5519_master_id_secret_key".

Tor will only need access to the medium term signing key and certificate as long as they are valid, so the master identity secret key can be kept outside DataDirectory/keys, on a storage media or a different computer. You'll have to manually renew the medium term signing key and certificate before they expire otherwise the Tor process on the relay will exit upon expiration.

If you want to use this feature, we have a guide about how to use and manage offline ed25519 identity keys. Click here to read it. - this will be a link to a full long guide, which I will write - subject of ticket #16645. Most probably we will include the same link in the manual and maybe other places as well.

Last edited 4 years ago by s7r (previous) (diff)

comment:4 Changed 4 years ago by nickm

Severity: Normal
Status: newneeds_review

comment:5 Changed 4 years ago by tyseom

Cc: tyseom added

comment:6 Changed 3 years ago by nickm

Keywords: TorCoreTeam201512 added

comment:7 Changed 3 years ago by nickm

Keywords: TorCoreTeam201601 201512-deferred added; TorCoreTeam201512 removed

Perhaps in January?

comment:8 Changed 3 years ago by nickm

This information looks good to me. Could somebody please add it to the FAQ?

Last edited 3 years ago by nickm (previous) (diff)

comment:9 Changed 3 years ago by nickm

Bulk-modify: It is February 2016, and no longer possible that anything else will get done in January 2016. Time's arrow and all that.

comment:10 Changed 3 years ago by nickm

Keywords: TorCoreTeam201602 added; TorCoreTeam201601 removed

comment:11 Changed 3 years ago by s7r

For direct links to these questions, they should have the following tags:

I want to upgrade/move my relay. How do I keep the same key? - #KeepRelayIdentity

How do offline ed25519 identity keys work? What do I need to know? - #OfflineEd25519Id

The link of the full guide mentioned in the last paragraph of the suggested faq text is:
https://trac.torproject.org/projects/tor/wiki/doc/TorRelaySecurity/OfflineKeys

Last edited 3 years ago by s7r (previous) (diff)

comment:12 Changed 3 years ago by nickm

Milestone: Tor: 0.2.7.x-finalTor: 0.2.8.x-final

comment:13 Changed 3 years ago by nickm

Milestone: Tor: 0.2.7.x-finalTor: 0.2.8.x-final

comment:14 Changed 3 years ago by nickm

Cc: sebastian added
Description: modified (diff)

comment:15 Changed 3 years ago by nickm

Description: modified (diff)

whoops. That should have been a comment, not a description change.

Sebastian, I think this is a website thing?

comment:16 Changed 3 years ago by Sebastian

Resolution: fixed
Status: needs_reviewclosed

reworded a little bit, hope you like it.

Note: See TracTickets for help on using tickets.