Relay keys and identities

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 (like KP_relayid_ed).

In an identifier, a KP_ prefix denotes a public key, and a 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. For example, a relay's identity key KP_relayid_ed MUST NOT also be used as its medium-term signing key KP_relaysign_ed.

Identity keys

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:

  • KP_relayid_ed, 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_ed key, which is used to sign other important keys and objects.

  • KP_relayid_rsa, 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.

We write KP_relayid to refer to a key which is either KP_relayid_rsa or KP_relayid_ed.

Online signing keys

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:

  • KP_relaysign_ed, 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 KP_relayid_ed key, producing a certificate of type IDENTITY_V_SIGNING. The KP_relayid_ed key is not used for anything else.

Circuit extension keys

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:

  • KP_ntor, KS_ntor: A curve25519 key used for the ntor and ntorv3 circuit extension handshakes.

  • KP_onion_tap, KS_onion_tap: A 1024 bit RSA key used for the obsolete TAP circuit extension handshake.

Channel authentication

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.

  • KP_link_ed, KS_link_ed. A short-term Ed25519 "link authentication" key, used to authenticate the link handshake: see "Negotiating and initializing channels". This key is signed by the "signing" key, and should be regenerated frequently.

Legacy channel authentication

These key types were used in older versions of the channel negotiation handshakes.

  • KP_legacy_linkauth_rsa, KS_legacy_linkauth_rsa: A 1024-bit RSA key, used to authenticate the link handshake. (No longer used in modern Tor.) It played a role similar to KP_link_ed.

As a convenience, to describe legacy versions of the link handshake, we give a name to the public key used for the TLS handshake itself:

  • KP_legacy_conn_tls, KS_legacy_conn_tls: A short term key used to for TLS connections. (No longer used in modern Tor.) This was another name for the server's TLS key, which at the time was required to be an RSA key. It was used in some legacy handshake versions.