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.)