diff options
Diffstat (limited to 'attic/text_formats/cert-spec.txt')
-rw-r--r-- | attic/text_formats/cert-spec.txt | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/attic/text_formats/cert-spec.txt b/attic/text_formats/cert-spec.txt new file mode 100644 index 0000000..a70e100 --- /dev/null +++ b/attic/text_formats/cert-spec.txt @@ -0,0 +1,198 @@ + + 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 created by signing all the fields in + the certificate up until "SIGNATURE" (that is, signing + sizeof(ed25519_cert) - 64 bytes). + +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".) + + Just like with the Ed25519 certificates above, the EXPIRATION_DATE + operates in HOURS after the epoch. + + 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.) |