[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [torspec/master] Document Ed25519 link authentication and EXTEND formats.



commit 85e4033f9c4640998e8edbfc1502e092515934e5
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
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"
 



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits