Every Tor relay has multiple public/private keypairs, with different lifetimes and purposes. We explain them here.
Each key here has an English name
(like "Ed25519 identity key")
and an unambiguous identifier
In an identifier,
KP_ prefix denotes a public key,
KS_ prefix denotes the corresponding secret key.
For historical reasons or reasons of space, you will sometimes encounter multiple English names for the same key, or shortened versions of that name. The identifier for a key, however, should always be unique and unambiguous.
For security reasons, all keys MUST be distinct:
the same key or keypair should never be used
for separate roles within the Tor protocol suite,
unless specifically stated.
a relay's identity key
MUST NOT also be used
as its medium-term signing key
An identity key is a long-lived key that uniquely identifies a relay. Two relays with the same set of identity keys are considered to be the same; any relay that changes its identity key is considered to have become a different relay.
An identity keypair's lifetime is the same as the lifetime of the relay.
Two identity keys are currently defined:
KS_relayid_ed: An "ed25519 identity key", also sometimes called a "master identity key".
This is an Ed25519 key. This key never expires. It is used for only one purpose: signing the
KP_relaysign_edkey, which is used to sign other important keys and objects.
KS_relayid_rsa: A legacy "RSA identity key".
This is an RSA key. It never expires. It is always 1024 bits long, and (as discussed above) its exponent must be 65537. It is used to sign directory documents and certificates.
Note that because the legacy RSA identity key is so short, it should not be assumed secure against an attacker. It exists for legacy purposes only. When authenticating a relay, a failure to prove an expected RSA identity is sufficient evidence of a failure to authenticate, but a successful proof of an RSA identity is not sufficient to establish a relay's identity. Parties SHOULD NOT use the RSA identity on its own.
KP_relayid to refer to a key which is either
Since Tor's design tries to support keeping the high-value Ed25519 relay identity key offline, we need a corresponding key that can be used for online signing:
KS_relaysign_ed: A medium-term Ed25519 "signing" key. This key is signed by the identity key
KP_relayid_ed, and must be kept online. A new one should be generated periodically. It signs nearly everything else, including directory objects, and certificates for other keys.
When this key is generated,
it needs to be signed with the
producing a certificate of type
KP_relayid_ed key is not used for anything else.
Each relay has one or more circuit extension keys (also called "onion keys"). When creating or extending a circuit, a client uses this key to perform a one-way authenticated key exchange with the target relay. If the recipient does not have the correct private key, the handshake will fail.
Circuit extension keys have moderate lifetimes, on the order of weeks. They are published as part of the directory protocol, and relays SHOULD accept handshakes for a while after publishing any new key. (The exact durations for these are set via a set of network parameters.)
There are two current kinds of circuit extension keys:
KS_onion_tap: A 1024 bit RSA key used for the obsolete
TAPcircuit extension handshake.
There are other keys that relays use to authenticate as part of their channel negotiation handshakes.
These keys are authenticated with other, longer lived keys. Relays MAY rotate them as often as they like, and SHOULD rotate them frequently—typically, at least once a day.
KS_legacy_conn_tls: A short-term RSA "Connection key" used to negotiate TLS connections. Tor implementations MAY rotate this key as often as they like, and SHOULD rotate this key at least once a day.
"Negotiating and initializing channels". This key is signed by the "signing" key, and should be regenerated frequently.. A short-term Ed25519 "link authentication" key, used to authenticate the link handshake: see