Ed25519 certificates in Tor Table of Contents 1. Scope and Preliminaries 1.1. Signing 1.2. Integer encoding 2. Document formats 2.1. Ed25519 Certificates 2.2. Basic extensions 2.2.1. Signed-with-ed25519-key extension [type 04] 2.3. RSA->Ed25519 cross-certificate A.1. List of certificate types (CERT_TYPE field) A.2. List of extension types A.3. List of signature prefixes A.4. List of certified key types (CERT_KEY_TYPE field) 1. Scope and Preliminaries This document describes a certificate format that Tor uses for its Ed25519 internal certificates. It is not the only certificate format that Tor uses. For the certificates that authorities use for their signing keys, see dir-spec.txt. Additionally, Tor uses TLS, which depends on X.509 certificates; see tor-spec.txt for details. The certificates in this document were first introduced in proposal 220, and were first supported by Tor in Tor version 0.2.7.2-alpha. 1.1. Signing All signatures here, unless otherwise specified, are computed using an Ed25519 key. In order to future-proof the format, before signing anything, the signed document is prefixed with a personalization string, which will be different in each case. 1.2. Integer encoding Network byte order (big-endian) is used to encode all integer values in Ed25519 certificates unless explicitly specified otherwise. 2. Document formats 2.1. Ed25519 Certificates When generating a signing key, we also generate a certificate for it. Unlike the certificates for authorities' signing keys, these certificates need to be sent around frequently, in significant numbers. So we'll choose a compact representation. VERSION [1 Byte] CERT_TYPE [1 Byte] EXPIRATION_DATE [4 Bytes] CERT_KEY_TYPE [1 byte] CERTIFIED_KEY [32 Bytes] N_EXTENSIONS [1 byte] EXTENSIONS [N_EXTENSIONS times] SIGNATURE [64 Bytes] 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 digest of some other key type depending on the value of CERT_KEY_TYPE. (See appendix A.4.) The EXPIRATION_DATE is a date, given in HOURS since the epoch, after which this certificate isn't valid. (A four-byte field here will work fine until 10136 A.D.) The EXTENSIONS field contains zero or more extensions, each of the format: ExtLength [2 bytes] ExtType [1 byte] ExtFlags [1 byte] ExtData [ExtLength bytes] The meaning of the ExtData field in an extension is type-dependent. The ExtFlags field holds flags; this flag is currently defined: 1 -- AFFECTS_VALIDATION. If this flag is present, then the extension affects whether the certificate is valid; clients must not accept the certificate as valid unless they understand the extension. It is an error for an extension to be truncated; such a certificate is invalid. Before processing any certificate, parties SHOULD 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. 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. 2.3. RSA->Ed25519 cross-certificate Certificate type [07] (Cross-certification of Ed25519 identity with RSA key) contains the following data: ED25519_KEY [32 bytes] EXPIRATION_DATE [4 bytes] SIGLEN [1 byte] SIGNATURE [SIGLEN bytes] 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".) This certificate type is used to mean, "This Ed25519 identity key acts with the authority of the RSA key that signed this certificate." A.1. List of certificate types (CERT_TYPE field) 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] - Ed25519 signing key with an identity key (see prop220 section 4.2) [05] - TLS link certificate signed with ed25519 signing key (see prop220 section 4.2) [06] - Ed25519 authentication key signed with ed25519 signing key (see prop220 section 4.2) **[07] - Reserved for RSA identity cross-certification; (see section 2.3 above, and tor-spec.txt section 4.2) [08] - Onion service: short-term descriptor signing key, signed with blinded public key. (See rend-spec-v3.txt, section [DESC_OUTER]) [09] - Onion service: intro point authentication key, cross-certifying the descriptor signing key. (See rend-spec-v3.txt, description of "auth-key") [0A] - ntor onion key cross-certifying ed25519 identity key (see dir-spec.txt, description of "ntor-onion-key-crosscert") [0B] - Onion service: ntor-extra encryption key, cross-certifying descriptor signing key. (see rend-spec-v3.txt, description of "enc-key-cert") A.2. List of extension types [04] - 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" (see dir-spec.txt) A.4. List of certified key types (CERT_KEY_TYPE field) [01] ed25519 key [02] SHA256 hash of an RSA key. (Not currently used.) [03] SHA256 hash of an X.509 certificate. (Used with certificate type 5.) (NOTE: Up till 0.4.5.1-alpha, all versions of Tor have incorrectly used "01" for all types of certified key. Implementations SHOULD allow "01" in this position, and infer the actual key type from the CERT_TYPE field.)