commit da9d48da01d44993cd25952ca7c0cc91a53962d8
Author: Nick Mathewson <nickm(a)torproject.org>
Date: Thu Feb 20 13:50:02 2014 +0000
Revise 220 to use a unified certificate format
---
proposals/220-ecc-id-keys.txt | 293 +++++++++++++++++++++++++++++------------
1 file changed, 209 insertions(+), 84 deletions(-)
diff --git a/proposals/220-ecc-id-keys.txt b/proposals/220-ecc-id-keys.txt
index b14fea7..153e0c9 100644
--- a/proposals/220-ecc-id-keys.txt
+++ b/proposals/220-ecc-id-keys.txt
@@ -2,7 +2,7 @@ Filename: 220-ecc-id-keys.txt
Title: Migrate server identity keys to Ed25519
Authors: Nick Mathewson
Created: 12 August 2013
-Target: 0.2.5.x
+Target: 0.2.x.x
Status: Draft
[Note: This is a draft proposal; I've probably made some important
@@ -74,25 +74,62 @@ Status: Draft
numbers. So we'll choose a compact representation.
VERSION [1 Byte]
- TYPE [1 Byte]
+ CERT_TYPE [1 Byte]
+ EXPIRATION_DATE [3 Bytes]
+ CERT_KEY_TYPE [1 byte]
CERTIFIED_KEY [32 Bytes]
- EXPIRATION_DATE [4 Bytes]
- EXTRA_STUFF [variable length]
+ EXTENSIONS [variable length, up to length of certificate
+ minus 64 bytes.]
SIGNATURE [64 Bytes]
- The "VERSION" field holds the value [01]. The "TYPE" field holds the
- value [01]. The CERTIFIED_KEY field is an Ed25519 public key. The
- expiration date is a day, given in DAYS since the epoch, after which
- this certificate isn't valid. The EXTRA_STUFF field is left for a
- future version of this format.
+ The "VERSION" field holds the value [01]. The "CERT_TYPE" field
+ holds a value depending on the type of certificate. (See appendix
+ A.1.) The CERTIFIED_KEY field is an Ed25519 public key if
+ CERT_KEY_TYPE is [01], or a SHA256 hash of some other key type
+ depending on the value of CERT_KEY_TYPE. The EXPIRATION_DATE is a
+ date, given in HOURS since the epoch, after which this
+ certificate isn't valid. (A three-byte field here will work fine
+ until 5797 A.D.)
- [XXXX Is "EXTRA_STUFF" a good idea? -NM]
+ The EXTENSIONS field contains zero or more extensions, each of
+ the format:
- Before processing any certificate, parties MUST know which identity
- key it is supposed to be signed by, and then check the signature.
- The signature is formed by signing the first N-64 bytes of the
- certificate prefixed with the string "Tor node signing key
- certificate v1".
+ ExtLength [1 or 2 bytes]
+ ExtType [1 or 2 bytes]
+ ExtData [Length bytes]
+
+ The ExtLength and ExtType fields can represent values between 0
+ and 2^15-1, representing values under 128 as "0xxxxxxx" and
+ values over 128 as "1xxxxxxx yyyyyyyy". The meaning of the
+ ExtData field in an extension is type-dependent.
+
+ It is an error for an extension to be truncated; such a
+ certificate is invalid.
+
+ Before processing any certificate, parties MUST know which
+ identity key it is supposed to be signed by, and then check the
+ signature. The signature is formed by signing the first N-64
+ bytes of the certificate prefixed with the string "Tor node
+ signing key certificate v1".
+
+2.2. Basic extensions
+
+2.2.1. Signed-with-ed25519-key extension [type 04]
+
+ In several places, it's desirable to bundle the key signing a
+ certificate along with the certificate. We do so with this
+ extension.
+
+ ExtLength = 32
+ ExtData =
+ An ed25519 key [32 bytes]
+
+ When this extension is present, it MUST match the key used to
+ sign the certificate.
+
+ This
+
+2.3. Revoking keys.
We also specify a revocation document for revoking a signing key or an
identity key. Its format is:
@@ -102,21 +139,22 @@ Status: Draft
IDENTITY_KEY [32 Bytes]
REVOKED_KEY [32 Bytes]
PUBLISHED [8 Bytes]
- EXTRA_STUFF [variable length]
+ REV_EXTENSIONS [variable length, up to length of revocation
+ document minus 64 bytes]
SIGNATURE [64 Bytes]
FIXED_PREFIX is "REVOKEID" or "REVOKESK". VERSION is [01]. KEYTYPE is
[01] for revoking a signing key or [02] for revoking an identity key.
REVOKED_KEY is the key being revoked; IDENTITY_KEY is the node's
Ed25519 identity key. PUBLISHED is the time that the document was
- generated, in seconds since the epoch. EXTRA_STUFF is left for a
+ generated, in seconds since the epoch. REV_EXTENSIONS is left for a
future version of this document. The SIGNATURE is generated with
the same key as in IDENTITY_KEY, and covers the entire revocation,
prefixed with "Tor key revocation v1".
- Using these revocation documents is unspecified.
+ Using these revocation documents is left for a later specification.
-2.2. Managing keys
+2.4. Managing keys
By default, we can keep the easy-to-setup key management properties
that Tor has now, so that node operators aren't required to have
@@ -138,20 +176,23 @@ Status: Draft
* If a Tor node's signing key is going to expire soon, it starts
warning the user. If it is expired, then the node shuts down.
-2.3. Router descriptors
+2.5. Router descriptors
We specify the following element that may appear at most once in
each router descriptor:
- "identity-ed25519" SP identity-key SP certification NL
+ "identity-ed25519" SP certificate NL
- The identity-key and certification are base64 encoded with
+ The identity-key and certificate are base64-encoded with
terminating =s removed. When this element is present, it MUST appear
as the first or second element in the router descriptor.
-
[XXX The rationale here is to allow extracting the identity key and
signing key and checking the signature before fully parsing the rest
of the document. -NM]
+ The certificate has CERT_TYPE of [04]. It must include a
+ signed-with-ed25519-key extension (see section 2.2.1), so that we
+ can extract the identity key.
+
When an identity-ed25519 element is present, there must also be a
"router-signature-ed25519" element. It MUST be the next-to-last
element in the descriptor, appearing immediately before the RSA
@@ -164,11 +205,9 @@ Status: Draft
Where 'signature' is encoded in base64 with terminating =s removed.
- The identity-key in the identity-ed25519 key MUST be the one used to
- sign the certification, and the signing key in the certification MUST
+ The signing key in the certificate MUST
be the one used to sign the document.
-
Note that these keys cross-certify as follows: the ed25519 identity
key signs the ed25519 signing key in the certificate. The ed25519
signing key signs itself and the ed25519 identity key and the RSA
@@ -176,7 +215,7 @@ Status: Draft
key also signs all three keys as part of signing the descriptor.
-2.3.1. Checking descriptor signatures.
+2.5.1. Checking descriptor signatures.
Current versions of Tor will handle these new formats by ignoring the
new fields, and not checking any ed25519 information.
@@ -197,7 +236,7 @@ Status: Draft
option, to be set to "always-on" in the future once enough clients
support it.
-2.3.2. Extra-info documents
+2.5.2. Extra-info documents
Extrainfo documents now include "identity-ed25519" and
"router-signature-ed25519" fields in the same positions in which they
@@ -208,7 +247,7 @@ Status: Draft
the router descriptor. (All versions of Tor that recognize this line
allow an extra field there.)
-2.3.3. A note on signature verification
+2.5.3. A note on signature verification
Here and elsewhere, we're receiving a certificate and a document
signed with the key certified by that certificate in the same step.
@@ -254,18 +293,18 @@ Status: Draft
3.2. Formats
- Vote and consensus documents now contain an optional "id" field for each
- routerstatus section. Its format is:
+ Vote and microdescriptor documents now contain an optional "id"
+ field for each routerstatus section. Its format is:
- "id" SP ed25519-identity NL
+ "id" SP "ed25519" SP ed25519-identity NL
where ed25519-identity is base64-encoded, with trailing = characters
omitted. In vote documents, it may be replaced by the format:
- "id" SP "none" NL
+ "id" SP "ed25519" SP "none" NL
which indicates that the node does not have an ed25519 identity. (In
- the consensus, a lack of "id" line means that the node has no ed25519
+ a microdescriptor, a lack of "id" line means that the node has no ed25519
identity.)
[XXXX Should the id entries in consensuses go into microdescriptors
@@ -337,46 +376,74 @@ Status: Draft
4. The link protocol
- [XXX This section won't make much sense unless you grok the v3
- connection protocol as described in tor-spec.txt, first proposed in
- proposal 195.]
+4.1. Overview of the status quo
+
+ This section won't make much sense unless you grok the v3
+ link protocol as described in tor-spec.txt, first proposed in
+ proposal 195. So let's review.
+
+ In the v3 link protocol, the client completes a TLS handshake
+ with the server, in which the server uses an arbitrary
+ certificate signed with an RSA key. The client then sends a
+ VERSIONS cell. The server replies with a VERSIONS cell to
+ negotiate version 3 or higher. The server also sends a CERTS
+ cell and an AUTH_CHALLENGE cell and a NETINFO cell.
+
+ The CERTS cell from the server contains a set of one or more
+ certificates that authenticate the RSA key used in the TLS
+ handshake. (Right now there's one self-signed RSA identity key
+ certificate, and one certificate signing the RSA link key with
+ the identity key. These certificates are X509.)
+
+ Having received a CERTS cell, the client has enough information
+ to authenticate the server. At this point, the client may send a
+ NETINFO cell to finish the handshake. But if the client wants to
+ authenticate as well, it can send a CERTS cell and an AUTENTICATE
+ cell.
+
+ The client's CERTS cell also contains certs of the same general
+ kinds as the server's key file: a self-signed identity
+ certificate, and an authentication certificate signed with the
+ identity key. The AUTHENTICATE cell contains a signature of
+ various fields, including the contents of the AUTH_CHALLENGE
+ which the server sent cell, using the client's authentication
+ key. These cells allow the client to authenticate to the server.
+
+
+4.2. Link protocol changes for ECC ID keys
We add four new CertType values for use in CERTS cells:
4: Ed25519 signing key
5: Link key certificate certified by Ed25519 signing key
- 6: TLS authentication key certified by Ed25519 signing key
- 7: RSA cross-certification for Ed25519 identity key
-
- The content of certificate type 4 is:
- Ed25519 identity key [32 bytes]
- Signing key certificate as in 2.1 above [variable length]
-
- The content of certificate type 5 is:
- CERT_DIGEST [32 bytes]
- EXPIRATION_DATE [4 bytes]
- EXTRA_STUFF [variable]
- SIGNATURE [64 bytes]
- where CERT_DIGEST is a SHA256 digest of the X.509 certificate used
- for the TLS link, EXPIRATION_DATE is a date in *days* since the epoch
- starting on which the certificate is invalid, and SIGNATURE is
- a signature using the signing key of the above two fields, prefixed
- with "Tor TLS link certificate check v1".
-
- The content of certificate type 6 is the same as the signing key in
- 2.1 above, except that the TYPE field is 02 and the fixed string used
- in signing is "". The Ed25519 key
- certified by this key can be used in AUTHENTICATE cells.
-
- The content of certificate type 7 is:
+ 6: Ed25519 TLS authentication key certified by Ed25519 signing key
+ 7: RSA cross-certificate for Ed25519 identity key
+ These correspond to types used in the CERT_TYPE field of
+ the certificates.
+
+ The content of certificate type [04] (Ed25519 signing key)
+ is as in section 2.5 above, containing an identity key and the
+ signing key, both signed by the identity key.
+
+ Certificate type [05] (Link certificate signed with Ed25519
+ signing key) contains a SHA256 digest of the X.509 link
+ certificate used on the TLS connection in its key field; it is
+ signed with the signing key.
+
+ Certificate type [06] (Ed25519 TLS authentication signed with
+ Ed25519 signing key) has the signing key used to sign the
+ AUTHENTICATE cell described later in this section.
+
+ Certificate type [07] (Cross-certification of Ed25519 identity
+ with RSA key) contains the following data:
ED25519_KEY [32 bytes]
EXPIRATION_DATE [4 bytes]
SIGNATURE [128 bytes]
- Here, the Ed25519 identity key is signed with router's identity key,
- to indicate that authenticating with a key certified by the Ed25519
- key counts as certifying with RSA identity key. (The signature is
- computed on the SHA256 hash of the non-signature parts of the
- certificate, prefixed with the string "Tor TLS RSA/Ed25519
- cross-certification".)
+ Here, the Ed25519 identity key is signed with router's RSA
+ identity key, to indicate that authenticating with a key
+ certified by the Ed25519 key counts as certifying with RSA
+ identity key. (The signature is computed on the SHA256 hash of
+ the non-signature parts of the certificate, prefixed with the
+ string "Tor TLS RSA/Ed25519 cross-certificate".)
(There's no reason to have a corresponding Ed25519-signed-RSA-key
certificate here, since we do not treat authenticating with an RSA
@@ -395,13 +462,16 @@ Status: Draft
"RSA-SHA256-TLSSecret", except that the CID and SID fields support
more key types; some strings are different, and the signature is
performed with Ed25519 using the authentication key from a type-6
- cert.
+ cert. Clients can send this AUTHENTICATE type if the server
+ lists it in its AUTH_CHALLENGE cell.
- TYPE: The characters "AUTH0002" [8 octets]
+ Modified values and new fields below are marked with asterisks.
+
+ TYPE: The characters "AUTH0002"* [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]
+ *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,
@@ -417,15 +487,13 @@ Status: Draft
- client_random, as sent in the TLS Client Hello
- server_random, as sent in the TLS Server Hello
- the NUL terminated ASCII string:
- "Tor V3 handshake TLS cross-certification with Ed25519"
+ "Tor V3 handshake TLS cross-certification with Ed25519"*
[32 octets]
- TIME: The time of day in seconds since the POSIX epoch. [8 octets]
- RAND: A 16 byte value, randomly chosen by the initiator. [16 octets]
- SIG: A signature of all previous fields using the initiator's
+ 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 flags.
[variable length]
-
If you've got a consensus that lists an ECC key for a node, but the
node doesn't give you an ECC key, then refuse this connection.
@@ -499,16 +567,17 @@ Status: Draft
"Rule 1" on the authorities. (Don't allow an Ed25519<->RSA pairing
to change.)
- Once 0.2.5.x is in beta or rc, turn on the consensus option for
- everyone who receives descriptors with Ed25519 identity keys to check
- them.
+ Once the release with these changes is in beta or rc, turn on the
+ consensus option for everyone who receives descriptors with
+ Ed25519 identity keys to check them.
- Once 0.2.5.x is in beta or rc, turn on the consensus option for
- clients to generate EXTEND2 requests with Ed25519 identity keys.
+ Once the release with these changes is in beta or rc, turn on the
+ consensus option for clients to generate EXTEND2 requests with
+ Ed25519 identity keys.
- Once 0.2.5.x has been stable for a month or two, turn on "Rule 2" on
- authorities. (Don't allow nodes that have advertised an Ed25519 key
- to stop.)
+ Once the release with these changes has been stable for a month
+ or two, turn on "Rule 2" on authorities. (Don't allow nodes that
+ have advertised an Ed25519 key to stop.)
9. Future proposals
@@ -519,3 +588,59 @@ Status: Draft
* Bridge identity support.
* Ed25519-aware family support
+A.1. List of certificate types
+
+ The values marked with asterisks are not types corresponding to
+ the certificate format of section 2.1. Instead, they are
+ reserved for RSA-signed certificates to avoid conflicts between
+ the certificate type enumeration of the CERTS cell and the
+ certificate type enumeration of in our Ed25519 certificates.
+
+
+ **[00],[01],[02],[03] - Reserved to avoid conflict with types used
+ in CERTS cells.
+
+ [04] - signing a signing key with an identity key (Section 2.5)
+
+ [05] - TLS link certificate signed with ed25519 signing key
+ (Section 4.2)
+
+ [06] - Ed25519 authentication key signed with ed25519 signing key
+ (Section 4.2)
+
+ **[07] - reserved for RSA identity cross-certification (Section 4.2)
+
+
+A.2. List of extension types
+
+
+ [01] - signed-with-ed25519-key (section 2.2.1)
+
+A.3. List of signature prefixes
+
+ We describe various documents as being signed with a prefix. Here
+ are those prefixes:
+
+ "Tor router descriptor signature v1" (section 2.5)
+ "Tor node signing key certificate v1" (section 2.1)
+
+A.4. List of certified key types
+
+ [01] ed25519 key
+ [02] SHA256 hash of an RSA key
+ [03] SHA256 hash of an X.509 certificate
+
+A.5. Reserved numbers
+
+ We need a new consensus algorithm number to encompass checking
+ ed25519 keys and putting them in microdescriptors.
+
+
+ We need new CertType values for use in CERTS cells. We reserved
+ in section 4.2.
+
+ 4: Ed25519 signing key
+ 5: Link key certificate certified by Ed25519 signing key
+ 6: TLS authentication key certified by Ed25519 signing key
+ 7: RSA cross-certificate for Ed25519 identity key
+
