1 files changed, 223 insertions, 0 deletions
diff --git a/spec/cert-spec.md b/spec/cert-spec.md
new file mode 100644
index 0000000..36c9c0b
--- /dev/null
+++ b/spec/cert-spec.md
@@ -0,0 +1,223 @@
+Ed25519 certificates in Tor
+
+Table of Contents
+
+```text
+    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)
+```
+
+<a id="cert-spec.txt-1"></a>
+# 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.
+
+<a id="cert-spec.txt-1.1"></a>
+## 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.
+
+<a id="cert-spec.txt-1.2"></a>
+## Integer encoding
+
+Network byte order (big-endian) is used to encode all integer values
+in Ed25519 certificates unless explicitly specified otherwise.
+
+<a id="cert-spec.txt-2"></a>
+# Document formats
+
+<a id="cert-spec.txt-2.1"></a>
+## 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.
+
+```text
+         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:
+
+```text
+         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).
+
+<a id="cert-spec.txt-2.2"></a>
+## Basic extensions
+
+<a id="cert-spec.txt-2.2.1"></a>
+### 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.
+
+```text
+        ExtLength = 32
+        ExtData =
+           An ed25519 key    [32 bytes]
+```
+
+When this extension is present, it MUST match the key used to
+sign the certificate.
+
+<a id="cert-spec.txt-2.3"></a>
+## RSA->Ed25519 cross-certificate
+
+Certificate type [07] (Cross-certification of Ed25519 identity
+with RSA key) contains the following data:
+
+```text
+       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 id="cert-spec.txt-A.1"></a>
+## 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.
+
+```text
+   **[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 id="cert-spec.txt-A.2"></a>
+## List of extension types
+
+[04] - signed-with-ed25519-key (section 2.2.1)
+
+<a id="cert-spec.txt-A.3"></a>
+## 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 id="cert-spec.txt-A.4"></a>
+## List of certified key types (CERT_KEY_TYPE field)
+
+```text
+   [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.)
+