Revise cert-spec

There is a lot more to do, but this makes the spec up-to-date and
gives it an accurate description of every cert type, with
cross-links to appropriate documentation elsewhere.

1 files changed, 191 insertions, 151 deletions

diff --git a/spec/cert-spec.md b/spec/cert-spec.md
index 141e1f8..ed827cd 100644
--- a/spec/cert-spec.md
+++ b/spec/cert-spec.md
@@ -1,191 +1,231 @@
-# Ed25519 certificates in Tor
+# Certificates in Tor
 
-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.
+This document describes a certificate formats that Tor uses for
+its Ed25519 internal certificates,
+and discusses how that format is labeled and encoded.
 
-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.
+This format is not the only certificate format that Tor uses.
+For the certificates that authorities use
+for their signing keys,
+see ["Creating key certificates"](dir-spec/creating-key-certificates.md).
 
-<a id="cert-spec.txt-1.1"></a>
-
-## Signing
+Additionally, Tor uses TLS, which depends on X.509 certificates.
 
-All signatures here, unless otherwise specified, are computed
-using an Ed25519 key.
+> 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.
 
-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.1"></a>
 
-<a id="cert-spec.txt-1.2"></a>
+## Signing
 
-## Integer encoding
+All signatures here, unless otherwise specified,
+are computed using an Ed25519 key.
 
-Network byte order (big-endian) is used to encode all integer values
-in Ed25519 certificates unless explicitly specified otherwise.
+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-2"></a>
 
 ## Document formats
 
+### X.509 certificates {#x509}
+
+Describing this format is out of scope
+for the Tor specifications.
+
 <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).
+### Ed25519 Certificates {#ed-certs}
 
-<a id="cert-spec.txt-2.2"></a>
+When generating a signing key,
+we also generate a certificate for it.
+These representation for this certificate is:
 
-### Basic extensions
+| Field            | Size | Description                         |
+| ---------------- | ---- | ----------------------------------- |
+| `VERSION`        | 1    | The version of this format          |
+| `CERT_TYPE`      | 1    | [Purpose and meaning of the cert](#list-cert-types) |
+| `EXPIRATION_DATE`| 4    | When the cert becomes invalid       |
+| `CERT_KEY_TYPE`  | 1    | [Type of `CERTIFIED_KEY`](#list-key-types) |
+| `CERTIFIED_KEY`  | 32   | Certified key, or its digest        |
+| `N_EXTENSIONS`   | 1    | Number of extensions                |
+| `N_EXTENSIONS` times: | |                                     |
+| - `ExtLen`       | 2    | Length of encoded extension body    |
+| - `ExtType`      | 1    | [Type of extension](#list-ext-types)|
+| - `ExtFlags`     | 1    | Control interpretation of extension |
+| - `ExtData`      | `ExtLen` | Encoded extension body          |
+| SIGNATURE        | 64   | Signature of all previous fields    |
 
-<a id="cert-spec.txt-2.2.1"></a>
 
-#### Signed-with-ed25519-key extension \[type 04\] { #signed-with-ed25519 }
+The `VERSION` field holds the value `[01]`.
 
-In several places, it's desirable to bundle the key signing a
-certificate along with the certificate.  We do so with this
-extension.
+The `CERT_TYPE` field holds a value depending on the type of certificate.
+(See ["Certificate types"](#list-cert-types).)
 
-```text
-        ExtLength = 32
-        ExtData =
-           An ed25519 key    [32 bytes]
-```
+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 ["List of certified key types"](#list-key-types).)
 
-When this extension is present, it MUST match the key used to
-sign the certificate.
+The `EXPIRATION_DATE` is a date, given in **hours** since the epoch,
+after which this certificate isn't valid.
 
-<a id="cert-spec.txt-2.3"></a>
+> (A four-byte date here will work fine until 10136 A.D.)
 
-### RSA->Ed25519 cross-certificate { #rsa-cross-cert }
+The `ExtFlags` field holds flags. Only one flag is currently defined:
 
-Certificate type \[07\] (Cross-certification of Ed25519 identity
-with RSA key) contains the following data:
+- **1**: `AFFECTS_VALIDATION`.
+  If this flag is present,
+  then the extension affects whether the certificate is valid;
+  implementations MUST NOT accept the certificate as valid
+  unless they recognize the `ExtType`
+  and accept the extension as valid.
 
-```text
-       ED25519_KEY                       [32 bytes]
-       EXPIRATION_DATE                   [4 bytes]
-       SIGLEN                            [1 byte]
-       SIGNATURE                         [SIGLEN bytes]
-```
+The interpretation of `ExtBody` depends on the `ExtType` field.
+See ["Recognized extensions"](#extensions) below.
 
-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".)
+It is an error for an extension to be truncated;
+such a certificate is invalid.
 
-Just like with the Ed25519 certificates above, the EXPIRATION_DATE
-operates in HOURS after the epoch.
+Before processing any certificate,
+parties SHOULD know which key it is supposed to be signed by,
+and then check the signature.
 
-This certificate type is used to mean, "This Ed25519 identity key
-acts with the authority of the RSA key that signed this
-certificate."
+The signature is created by signing all the fields in the certificate
+up until but not including `SIGNATURE`.
 
-<a id="cert-spec.txt-A.1"></a>
 
-## List of certificate types (CERT_TYPE field) { #list-cert-types }
+<a id="cert-spec.txt-2.2"></a>
 
-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.
+### Recognized extensions {#extensions}
 
-```text
-   **[00],[01],[02],[03] - Reserved to avoid conflict with types used
-          in CERTS cells.
+<a id="cert-spec.txt-2.2.1"></a>
 
-   [04] - Ed25519 signing key with an identity key
-          (see prop220 section 4.2)
+#### Signed-with-ed25519-key extension \[type 04\] { #signed-with-ed25519 }
 
-   [05] - TLS link certificate signed with ed25519 signing key
-          (see prop220 section 4.2)
+In several places,
+it's desirable to bundle the signing key
+along with the certificate.
+We do so with this extension.
 
-   [06] - Ed25519 authentication key signed with ed25519 signing key
-          (see prop220 section 4.2)
+With this extension:
+- `ExtLen` is 32.
+- `ExtData is a 32-byte Ed25519 public key.
 
-   **[07] - Reserved for RSA identity cross-certification;
-          (see section 2.3 above, and tor-spec.txt section 4.2)
+When this extension is present,
+it MUST match the key used to sign the certificate.
 
-   [08] - Onion service: short-term descriptor signing key, signed
-          with blinded public key.
-          (See rend-spec-v3.txt, section [DESC_OUTER])
+<a id="cert-spec.txt-2.3"></a>
 
-   [09] - Onion service: intro point authentication key, cross-certifying the
-          descriptor signing key.
-          (See rend-spec-v3.txt, description of "auth-key")
+### RSA→Ed25519 cross-certificate { #rsa-cross-cert }
+
+In one place,
+we have a binary certificate that signs an Ed25519 key
+using a legacy 1024-bit RSA key.
+Its format is:
+
+| Field             | Size | Description |
+| ----------------- | ---- | ----------- |
+| `ED25519_KEY`     | 32   | The subject key
+| `EXPIRATION_DATE` | 4    | When the cert becomes invalid |
+| `SIGLEN`          | 1    | Length of RSA signature. |
+| `SIGNATURE`       | `SIGLEN` | RSA Signature |
+
+Just as with the
+[Ed25519 certificates above](#ed-certs),
+the `EXPIRATION_DATE` field is a number of **hours**
+since the epoch.
+
+As elsewhere,
+the RSA signature is generated using RSA-PKCSv1 padding,
+with hash algorithm OIDs omitted.
+
+The signature is computed on the SHA256 hash of
+`PREFIX | FIELDS`,
+where `PREFIX` is the string
+`"Tor TLS RSA/Ed25519 cross-certificate"`
+(without any terminating NUL),
+and `FIELDS` is all other fields in the certificate
+(other than the signature itself).
 
-   [0A] - ntor onion key cross-certifying ed25519 identity key
-          (see dir-spec.txt, description of "ntor-onion-key-crosscert")
+<a id="cert-spec.txt-A.1"></a>
 
-   [0B] - Onion service: ntor-extra encryption key, cross-certifying
-          descriptor signing key.
-          (see rend-spec-v3.txt, description of "enc-key-cert")
-```
+## Certificate types (CERT_TYPE field) { #list-cert-types }
+
+This table shows values of the `CERT_TYPE` field in Ed,
+as well as values of the `CertType` field
+used in a [`CERTS` cell](./tor-spec/negotiating-channels.md#CERTS-cells)
+during channel negotiation.
+
+> You might ned to scroll this table to view it all.
+>
+> We'll try to fix this once we have a better grip on our mdbook CSS.
+
+| Type | Mnemonic         | Format | Subject                 | Signing key         | Reference | Notes |
+|------| -------------    | ------ | ----------------------- | ------------        | --------- | ----- |
+|`[01]`| `TLS_LINK_X509`  | [X.509]| [`KP_legacy_conn_tls`]  | [`KS_relayid_rsa`]  | [Legacy channel negotiation] | Obsolete |
+|`[02]`| `RSA_ID_X509`    | [X.509]| [`KP_relayid_rsa`]      | [`KS_relayid_rsa`]  | [Legacy channel negotiation] | Obsolete |
+|`[03]`| `LINK_AUTH_X509` | [X.509]| ? | ?                                         | [Legacy channel negotiation] | Obsolete |
+|`[04]`| `IDENTITY_V_SIGNING` |[Ed]| [`KP_relaysign_ed`]     | [`KS_relayid_ed`]   | [Online signing keys] | |
+|`[05]`| `SIGNING_V_TLS_CERT` |[Ed]| A TLS certificate       | [`KS_relaysign_ed`] | [CERTS cells] | |
+|`[06]`| `SIGNING_V_LINK_AUTH`|[Ed]| [`KP_link_ed`]          | [`KS_relaysign_ed`] | [CERTS cells] | |
+|`[07]`| `RSA_ID_V_IDENTITY`  |[Rsa]|[`KP_relayid_ed`]       | [`KS_relayid_rsa`]  | [CERTS cells] | |
+|`[08]`| `BLINDED_ID_V_SIGNING`|[Ed]|[`KP_hs_desc_sign`]     | [`KS_hs_blind_id`]  | [HsDesc (outer)] | |
+|`[09]`| `HS_IP_V_SIGNING`    |[Ed]| [`KP_hs_ipt_sid`]       | [`KS_hs_desc_sign`] | [HsDesc (`auth-key`)] | Backwards, see [note 1](#note-1) |
+|`[0A]`| `NTOR_CC_IDENTITY`   |[Ed]| [`KP_relayid_ed`]       | [`EdCvt`]`(`[`KS_ntor`]`)` | [ntor cross-cert] | |
+|`[0B]`| `HS_IP_CC_SIGNING`   |[Ed]| [`KP_hss_ntor`]         | [`KS_hs_desc_sign`]  | [HsDesc (`enc-key-cert`)] | Backwards, see [note 1](#note-1) |
+
+
+<!-- TODO: Figure out what [03] was for! -->
+
+[X.509]: #x509
+[Rsa]: #rsa-cross-cert
+[Ed]: #ed-certs
+[`KP_legacy_conn_tls`]: ./tor-spec/relay-keys.md#legacy_conn_tls
+[`KP_relayid_rsa`]: ./tor-spec/relay-keys.md#relayid_rsa
+[`KP_relaysign_ed`]:  ./tor-spec/relay-keys.md#relaysign_ed
+[`KP_relayid_ed`]:  ./tor-spec/relay-keys.md#relayid_ed
+[`KP_link_ed`]:  ./tor-spec/relay-keys.md#link_ed
+[`KS_legacy_conn_tls`]: ./tor-spec/relay-keys.md#legacy_conn_tls
+[`KS_relayid_rsa`]: ./tor-spec/relay-keys.md#relayid_rsa
+[`KS_relaysign_ed`]:  ./tor-spec/relay-keys.md#relaysign_ed
+[`KS_relayid_ed`]:  ./tor-spec/relay-keys.md#relayid_ed
+[`KS_ntor`]: ./tor-spec/relay-keys.md#ntor
+[`KS_link_ed`]:  ./tor-spec/relay-keys.md#link_ed
+[`KP_hs_desc_sign`]: ./rend-spec/protocol-overview.md#hs_desc_sign
+[`KS_hs_desc_sign`]: ./rend-spec/protocol-overview.md#hs_desc_sign
+[`KP_hs_ipt_sid`]:  ./rend-spec/protocol-overview.md#hs_ipt_sid
+[`KP_hss_ntor`]: ./rend-spec/protocol-overview.md#hss_ntor
+[`KS_hs_blind_id`]: ./rend-spec/protocol-overview.md#hs_blind_id
+[Legacy channel negotiation]: ./tor-spec/obsolete-channels.md
+[Online signing keys]: ./tor-spec/relay-keys.md#online-signing
+[CERTS cells]: ./tor-spec/negotiating-channels.md#CERTS-cells
+[`EdCvt`]: ./dir-spec/converting-to-ed25519.md
+[HsDesc (outer)]: ./rend-spec/hsdesc-outer.md#descriptor-signing-key-cert
+[HsDesc (`auth-key`)]: ./rend-spec/hsdesc-encrypt.md#auth-key
+[HsDesc (`enc-key-cert`)]: ./rend-spec/hsdesc-encrypt.md#enc-key-cert
+[ntor cross-cert]: ./dir-spec/server-descriptor-format.md#ntor-onion-key-crosscert
+
+
+<span id="note-1">Note 1:
+The certificate types
+[`[09] HS_IP_V_SIGNING`][HsDesc (`auth-key`)]
+and
+[`[0B] HS_IP_CC_SIGNING`][HsDesc (`enc-key-cert`)]
+were implemented incorrectly, and now cannot be changed.
+Their signing keys and subject keys, as implemented,
+are given in the table.
+They were originally meant to be the inverse of this order.
+</span>
 
 <a id="cert-spec.txt-A.2"></a>
 
 ## List of extension types { #list-ext-types }
 
-\[04\] - signed-with-ed25519-key (section 2.2.1)
+- `[04]` - [signed-with-ed25519-key](#signed-with-ed25519)
 
 <a id="cert-spec.txt-A.3"></a>
 
@@ -200,14 +240,14 @@ are those prefixes:
 
 ## List of certified key types (CERT_KEY_TYPE field) { #list-key-types }
 
-```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
+- `[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.)
+> (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.
+