[tor-commits] [torspec/master] Document Ed25519 link authentication and EXTEND formats.
nickm at torproject.org
nickm at torproject.org
Wed Sep 20 17:44:08 UTC 2017
commit 85e4033f9c4640998e8edbfc1502e092515934e5
Author: Nick Mathewson <nickm at torproject.org>
Date: Wed Sep 20 13:43:56 2017 -0400
Document Ed25519 link authentication and EXTEND formats.
---
tor-spec.txt | 202 +++++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 168 insertions(+), 34 deletions(-)
diff --git a/tor-spec.txt b/tor-spec.txt
index 4dc1ab4..5ff70af 100644
--- a/tor-spec.txt
+++ b/tor-spec.txt
@@ -185,8 +185,10 @@ see tor-design.pdf.
kept offline.
- A medium-term "signing" key. This key is signed by the master identity
key, and must be kept online. A new one should be generated
- periodically.
- - A short-term "link authentication" key. Not yet used.
+ periodically. It signs nearly everything else.
+ - A short-term "link authentication" key, used to authenticate
+ the link handshake: see section 4 below. This key is signed
+ by the "signing" key, and should be regenerated frequently.
The RSA identity key and Ed25519 master identity key together identify a
router uniquely. Once a router has used an Ed25519 master identity key
@@ -589,17 +591,49 @@ see tor-design.pdf.
Any extra octets at the end of a CERTS cell MUST be ignored.
- CertType values are:
+ Relevant certType values are:
1: Link key certificate certified by RSA1024 identity
- 2: RSA1024 Identity certificate
- 3: RSA1024 AUTHENTICATE cell link certificate
+ 2: RSA1024 Identity certificate, self-signed.
+ 3: RSA1024 AUTHENTICATE cell link certificate, signed with RSA1024 key.
+ 4: Ed25519 signing key, signed with identity key.
+ 5: TLS link certificate, signed with ed25519 signing key.
+ 6: Ed25519 AUTHENTICATE cell key, signed with ed25519 signing key.
+ 7: Ed25519 identity, signed with RSA identity.
- The certificate format for the above certificate types is DER encoded
- X509.
+ The certificate format for certificate types 1-3 is DER encoded
+ X509. For others, the format is as documented in cert-spec.txt.
+ Note that type 7 uses a different format from types 4-6.
A CERTS cell may have no more than one certificate of each CertType.
- To authenticate the responder, the initiator MUST check the following:
+
+ To authenticate the responder as having a given Ed25519,RSA identity key
+ combination, the initiator MUST check the following.
+ * The CERTS cell contains exactly one CertType 2 "ID" certificate.
+ * The CERTS cell contains exactly one CertType 4 Ed25519
+ "Id->Signing" cert.
+ * The CERTS cell contains exactly one CertType 5 Ed25519
+ "Signing->link" certificate.
+ * The CERTS cell contains exactly one CertType 7 "RSA->Ed25519"
+ cross-certificate.
+ * All X.509 certificates above have validAfter and validUntil dates;
+ no X.509 or Ed25519 certificates are expired.
+ * All certificates are correctly signed.
+ * The certified key in the Signing->Link certificate matches the
+ SHA256 digest of the certificate that was used to
+ authenticate the TLS connection.
+ * The identity key listed in the ID->Signing cert was used to
+ sign the ID->Signing Cert.
+ * The Signing->Link cert was signed with the Signing key listed
+ in the ID->Signing cert.
+ * The RSA->Ed25519 cross-certificate certifies the Ed25519
+ identity, and is signed with the RSA identity listed in the
+ "ID" certificate.
+ * The certified key in the ID certificate is a 1024-bit RSA key.
+ * The RSA ID certificate is correctly self-signed.
+
+ To authenticate the responder as having a given RSA identity only,
+ the initiator MUST check the following:
* The CERTS cell contains exactly one CertType 1 "Link" certificate.
* The CERTS cell contains exactly one CertType 2 "ID" certificate.
* Both certificates have validAfter and validUntil dates that
@@ -612,12 +646,37 @@ see tor-design.pdf.
* The link certificate is correctly signed with the key in the
ID certificate
* The ID certificate is correctly self-signed.
- Checking these conditions is sufficient to authenticate that the
- initiator is talking to the Tor node with the expected identity,
- as certified in the ID certificate.
- To authenticate the initiator, the responder MUST check the
- following:
+ In both cases above, checking these conditions is sufficient to
+ authenticate that the initiator is talking to the Tor node with the
+ expected identity, as certified in the ID certificate(s).
+
+
+ To authenticate the initiator as having a given Ed25519,RSA
+ identity key combination, the responder MUST check the following:
+ * The CERTS cell contains exactly one CertType 2 "ID" certificate.
+ * The CERTS cell contains exactly one CertType 4 Ed25519
+ "Id->Signing" certificate.
+ * The CERTS cell contains exactly one CertType 6 Ed25519
+ "Signing->auth" certificate.
+ * The CERTS cell contains exactly one CertType 7 "RSA->Ed25519"
+ cross-certificate.
+ * All X.509 certificates above have validAfter and validUntil dates;
+ no X.509 or Ed25519 certificates are expired.
+ * All certificates are correctly signed.
+ * The identity key listed in the ID->Signing cert was used to
+ sign the ID->Signing Cert.
+ * The Signing->AUTH cert was signed with the Signing key listed
+ in the ID->Signing cert.
+ * The RSA->Ed25519 cross-certificate certifies the Ed25519
+ identity, and is signed with the RSA identity listed in the
+ "ID" certificate.
+ * The certified key in the ID certificate is a 1024-bit RSA key.
+ * The RSA ID certificate is correctly self-signed.
+
+
+ To authenticate the initiator as having an RSA identity key only,
+ the responder MUST check the following:
* The CERTS cell contains exactly one CertType 3 "AUTH" certificate.
* The CERTS cell contains exactly one CertType 2 "ID" certificate.
* Both certificates have validAfter and validUntil dates that
@@ -633,6 +692,7 @@ see tor-design.pdf.
initiator has the ID it claims; to do so, the cells in 4.3 and 4.4
below must be exchanged.
+
4.3. AUTH_CHALLENGE cells
An AUTH_CHALLENGE cell is a variable-length cell with the following
@@ -648,20 +708,21 @@ see tor-design.pdf.
The Challenge field is a randomly generated string that the
initiator must sign (a hash of) as part of authenticating. The
methods are the authentication methods that the responder will
- accept. Only one authentication method is defined right now:
- see 4.4 below.
+ accept. Only two authentication methods are defined right now:
+ see 4.4.1 and 4.4.2 below.
4.4. AUTHENTICATE cells
If an initiator wants to authenticate, it responds to the
AUTH_CHALLENGE cell with a CERTS cell and an AUTHENTICATE cell.
The CERTS cell is as a server would send, except that instead of
- sending a CertType 1 cert for an arbitrary link certificate, the
- client sends a CertType 3 cert for an RSA AUTHENTICATE key.
- (This difference is because we allow any link key type on a TLS
- link, but the protocol described here will only work for 1024-bit
- RSA keys. A later protocol version should extend the protocol
- here to work with non-1024-bit, non-RSA keys.)
+ sending a CertType 1 (and possibly CertType 5) certs for arbitrary link
+ certificates, the initiator sends a CertType 3 (and possibly
+ CertType 6) cert for an RSA/Ed25519 AUTHENTICATE key.
+
+ This difference is because we allow any link key type on a TLS
+ link, but the protocol described here will only work for specific key
+ types as described in 4.4.1 and 4.4.2 below.
An AUTHENTICATE cell contains the following:
@@ -670,8 +731,17 @@ see tor-design.pdf.
Authentication [AuthLen octets]
Responders MUST ignore extra bytes at the end of an AUTHENTICATE
- cell. If AuthType is 1 (meaning "RSA-SHA256-TLSSecret"), then the
- Authentication contains the following:
+ cell. Recognized AuthTypes are 1 and 3, described in the next
+ two sections.
+
+ Initiators MUST NOT send an AUTHENTICATE cell before they have
+ verified the certificates presented in the responder's CERTS
+ cell, and authenticated the responder.
+
+4.4.1. Link authentication type 1: RSA-SHA256-TLSSecret
+
+ If AuthType is 1 (meaning "RSA-SHA256-TLSSecret"), then the
+ Authentication field of the AUTHENTICATE cell contains the following:
TYPE: The characters "AUTH0001" [8 octets]
CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets]
@@ -707,11 +777,51 @@ see tor-design.pdf.
from TYPE through TLSSECRETS contain their unique
correct values as described above, and then verifies the signature.
The server MUST ignore any extra bytes in the signed data after
- the SHA256 hash.
+ the RAND field.
- Initiators MUST NOT send an AUTHENTICATE cell before they have
- verified the certificates presented in the responder's CERTS
- cell, and authenticated the responder.
+ Responders MUST NOT accept this AuthType if the initiator has
+ claimed to have an Ed25519 identity.
+
+ (There is no AuthType 2: It was reserved but never implemented.)
+
+4.4.2. Link authentication type 3: Ed25519-SHA256-RFC5705.
+
+ If AuthType is 3, meaning "Ed25519-SHA256-RFC5705", the
+ Authentication field of the AuthType cell is as below:
+
+ Modified values and new fields below are marked with asterisks.
+
+ TYPE: The characters "AUTH0003" [8 octets]
+ CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets]
+ SID: A SHA256 hash of the responder's RSA1024 identity key [32 octets]
+ CID_ED: The initiator's Ed25519 identity key [32 octets]
+ SID_ED: The responder's Ed25519 identity key, or all-zero. [32 octets]
+ SLOG: A SHA256 hash of all bytes sent from the responder to the
+ initiator as part of the negotiation up to and including the
+ AUTH_CHALLENGE cell; that is, the VERSIONS cell, the CERTS cell,
+ the AUTH_CHALLENGE cell, and any padding cells. [32 octets]
+ CLOG: A SHA256 hash of all bytes sent from the initiator to the
+ responder as part of the negotiation so far; that is, the
+ VERSIONS cell and the CERTS cell and any padding cells. [32
+ octets]
+ SCERT: A SHA256 hash of the responder's TLS link certificate. [32
+ octets]
+ TLSSECRETS: The output of an RFC5705 Exporter function on the
+ TLS session, using as its inputs:
+ - The label string "EXPORTER FOR TOR TLS CLIENT BINDING AUTH0003"
+ - The context value equal to the initiator's Ed25519 identity key.
+ - The length 32.
+ [32 octets]
+ RAND: A 24 byte value, randomly chosen by the initiator. [24 octets]
+ SIG: A signature of all previous fields using the initiator's
+ Ed25519 authentication key (as in the cert with CertType 6).
+ [variable length]
+
+ To check the AUTHENTICATE cell, a responder checks that all fields
+ from TYPE through TLSSECRETS contain their unique
+ correct values as described above, and then verifies the signature.
+ The server MUST ignore any extra bytes in the signed data after
+ the RAND field.
4.5. NETINFO cells
@@ -849,6 +959,9 @@ see tor-design.pdf.
A sixteen-byte IPv6 address plus two-byte ORPort
[02] Legacy identity
A 20-byte SHA1 identity fingerprint. At most one may be listed.
+ [03] Ed25519 identity
+ A 32-byte Ed25519 identity fingerprint. At most one may
+ be listed.
Nodes MUST ignore unrecognized specifiers, and MUST accept multiple
instances of specifiers other than 'legacy identity'.
@@ -859,11 +972,25 @@ see tor-design.pdf.
Onion skin [TAP_C_HANDSHAKE_LEN bytes]
Identity fingerprint [HASH_LEN bytes]
- The "legacy identity" and "identity fingerprint fields are the SHA1
- hash of the PKCS#1 ASN1 encoding of the next onion router's identity
- (signing) key. (See 0.3 above.) Including this hash allows the
- extending OR verify that it is indeed connected to the correct target
- OR, and prevents certain man-in-the-middle attacks.
+ The "legacy identity" and "identity fingerprint" fields are the
+ SHA1 hash of the PKCS#1 ASN1 encoding of the next onion router's
+ identity (signing) key. (See 0.3 above.) The "Ed25519 identity"
+ field is the Ed25519 identity key of the target node. Including
+ this key information allows the extending OR verify that it is
+ indeed connected to the correct target OR, and prevents certain
+ man-in-the-middle attacks.
+
+ Extending ORs MUST check _all_ provided identity keys (if they
+ recognize the format), and and MUST NOT extend the circuit if the
+ target OR did not prove its ownership of any such identity key.
+ If only one identity key is provided, but the extending OR knows
+ the other (from directory information), then the OR SHOULD also
+ enforce that key.
+
+ If an extending OR has a channel with a given Ed25519 ID and RSA
+ identity, and receives a request for that Ed25519 ID and a
+ different RSA identity, it SHOULD NOT attempt to make another
+ connection: it should just fail and DESTROY the circuit.
The payload of an EXTENDED cell is the same as the payload of a
CREATED cell.
@@ -878,6 +1005,10 @@ see tor-design.pdf.
by a node running a version of Tor too old to support EXTEND2. In
other cases, clients SHOULD use EXTEND2.
+ When generating an EXTEND2 cell, clients SHOULD include the target's
+ Ed25519 identity whenever the target has one, and whenever the
+ target supports LinkAuth subprotocol version "3". (See section 9.2.)
+
When encoding a non-TAP handshake in an EXTEND cell, clients SHOULD
use the format with 'client handshake type tag'.
@@ -1741,11 +1872,14 @@ see tor-design.pdf.
LinkAuth protocols correspond to varieties of Authenticate cells used for
the v3+ link protocools.
- The current version is "1".
+ Current versions are:
+
+ "1" is the RSA link authentication described in section 4.4.1 above.
"2" is unused, and reserved by proposal 244.
- "3" is the ed25519 link handshake of proposal 220.
+ "3" is the ed25519 link authentication described in 4.4.2 above.
+
9.3. "Relay"
More information about the tor-commits
mailing list