Merge branch 'certs-revision' into 'main'

Revise cert-spec

See merge request tpo/core/torspec!221

7 files changed, 259 insertions, 163 deletions

diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md
index e08c8f7..ade9586 100644
--- a/spec/SUMMARY.md
+++ b/spec/SUMMARY.md
@@ -30,7 +30,7 @@
     - [Remote hostname lookup](./tor-spec/remote-hostname-lookup.md)
   - [Flow control](./tor-spec/flow-control.md)
   - [Subprotocol versioning](./tor-spec/subprotocol-versioning.md)
-  - [`Ed25519 certificates in Tor`](./cert-spec.md)
+  - [Certificates in Tor](./cert-spec.md)
 - [`Tor directory protocol, version 3`](./dir-spec/index.md)
   - [Outline](./dir-spec/outline.md)
   - [Router operation and formats](./dir-spec/router-operation-formats.md)
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.
+
diff --git a/spec/dir-spec/server-descriptor-format.md b/spec/dir-spec/server-descriptor-format.md
index 9a0c175..9cfaeea 100644
--- a/spec/dir-spec/server-descriptor-format.md
+++ b/spec/dir-spec/server-descriptor-format.md
@@ -178,6 +178,7 @@ subsequent descriptor.
 
 \[Before Tor 0.4.5.1-alpha, this field was optional.\]
 
+<a id="ntor-onion-key-crosscert"></a>
 ```text
     "ntor-onion-key-crosscert" SP Bit NL
            "-----BEGIN ED25519 CERT-----" NL certificate
diff --git a/spec/rend-spec/hsdesc-encrypt.md b/spec/rend-spec/hsdesc-encrypt.md
index 09aacbd..f267dcb 100644
--- a/spec/rend-spec/hsdesc-encrypt.md
+++ b/spec/rend-spec/hsdesc-encrypt.md
@@ -218,16 +218,18 @@ parameters as follows:
 After decrypting the second layer ciphertext, clients can finally learn the
 list of intro points etc. The plaintext has the following format:
 
+```text
 "create2-formats" SP formats NL
 
 \[Exactly once\]
 
-```text
       A space-separated list of integers denoting CREATE2 cell HTYPEs
       (handshake types) that the server recognizes. Must include at least
       ntor as described in tor-spec.txt. See tor-spec section 5.1 for a list
       of recognized handshake types.
+```
 
+```text
      "intro-auth-required" SP types NL
 
       [At most once]
@@ -236,7 +238,9 @@ list of intro points etc. The plaintext has the following format:
       section [INTRO-AUTH] for more info. A client that does not support at
       least one of these authentication types will not be able to contact the
       host. Recognized types are: 'ed25519'.
+```
 
+```text
      "single-onion-service"
 
       [At most once]
@@ -245,7 +249,9 @@ list of intro points etc. The plaintext has the following format:
       Service (see prop260 for more details about that type of service). This
       field has been introduced in 0.3.0 meaning 0.2.9 service don't include
       this.
+```
 
+```text
      "pow-params" SP type SP seed-b64 SP suggested-effort
                   SP expiration-time NL
 
@@ -274,10 +280,12 @@ list of intro points etc. The plaintext has the following format:
         expiration-time: A timestamp in "YYYY-MM-DDTHH:MM:SS" format (iso time
                          with no space) after which the above seed expires and
                          is no longer valid as the input for PoW.
+```
 
-     Followed by zero or more introduction points as follows (see section
-     [NUM_INTRO_POINT] below for accepted values):
+Followed by zero or more introduction points as follows (see section
+\[NUM_INTRO_POINT\] below for accepted values):
 
+```text
         "introduction-point" SP link-specifiers NL
 
           [Exactly once per introduction point at start of introduction
@@ -309,7 +317,9 @@ list of intro points etc. The plaintext has the following format:
           The client MAY reject the list of link specifiers if it is
           inconsistent with relay information from the directory, but SHOULD
           NOT modify it.
+```
 
+```text
         "onion-key" SP "ntor" SP key NL
 
           [Exactly once per introduction point]
@@ -317,7 +327,9 @@ list of intro points etc. The plaintext has the following format:
           The key is a base64 encoded curve25519 public key which is the onion
           key of the introduction point Tor node used for the ntor handshake
           when a client extends to it.
+```
 
+```text
         "onion-key" SP KeyType SP key.. NL
 
           [Any number of times]
@@ -325,7 +337,10 @@ list of intro points etc. The plaintext has the following format:
           Implementations should accept other types of onion keys using this
           syntax (where "KeyType" is some string other than "ntor");
           unrecognized key types should be ignored.
+```
 
+<a id="auth-key"></a>
+```text
         "auth-key" NL certificate NL
 
           [Exactly once per introduction point]
@@ -345,14 +360,18 @@ list of intro points etc. The plaintext has the following format:
           descriptor, which is _already_ signed by `KP_hs_desc_sign`,
           the verification aspect of this certificate serves no point in
           its current form.)
+```
 
+```text
         "enc-key" SP "ntor" SP key NL
 
           [Exactly once per introduction point]
 
           The key is a base64 encoded curve25519 public key used to encrypt
           the introduction request to service. (`KP_hss_ntor`)
+```
 
+```text
         "enc-key" SP KeyType SP key.. NL
 
           [Any number of times]
@@ -360,7 +379,10 @@ list of intro points etc. The plaintext has the following format:
           Implementations should accept other types of onion keys using this
           syntax (where "KeyType" is some string other than "ntor");
           unrecognized key types should be ignored.
+```
 
+<a id="enc-key-cert"></a>
+```text
         "enc-key-cert" NL certificate NL
 
           [Exactly once per introduction point]
diff --git a/spec/rend-spec/hsdesc-outer.md b/spec/rend-spec/hsdesc-outer.md
index ea623b8..f67fc6c 100644
--- a/spec/rend-spec/hsdesc-outer.md
+++ b/spec/rend-spec/hsdesc-outer.md
@@ -23,7 +23,10 @@ meta-format from dir-spec.txt.
 
        The LifetimeMinutes field can take values between 30 and 720 (12
        hours).
+```
 
+<a id="descriptor-signing-key-cert"></a>
+```text
     "descriptor-signing-key-cert" NL certificate NL
 
        [Exactly once.]
@@ -33,7 +36,9 @@ meta-format from dir-spec.txt.
        certificate cross-certifies the short-term descriptor signing key with
        the blinded public key.  The certificate type must be [08], and the
        blinded public key must be present as the signing-key extension.
+```
 
+```text
      "revision-counter" SP Integer NL
 
        [Exactly once.]
@@ -49,7 +54,9 @@ meta-format from dir-spec.txt.
 
        Implementations MUST be able to parse 64-bit values for these
        counters.
+```
 
+```text
      "superencrypted" NL encrypted-string
 
        [Exactly once.]
@@ -58,7 +65,9 @@ meta-format from dir-spec.txt.
        blob is base64 encoded and enclosed in -----BEGIN MESSAGE---- and
        ----END MESSAGE---- wrappers. (The resulting document does not end with
        a newline character.)
+```
 
+```text
      "signature" SP signature NL
 
        [exactly once, at end.]
diff --git a/spec/rend-spec/protocol-overview.md b/spec/rend-spec/protocol-overview.md
index afc2dd1..10c67b9 100644
--- a/spec/rend-spec/protocol-overview.md
+++ b/spec/rend-spec/protocol-overview.md
@@ -221,6 +221,7 @@ keypair you can do ECDSA with."\]
 
 Public/private keypairs defined in this document:
 
+<a id="hs_id"></a>
 ```text
       Master (hidden service) identity key -- A master signing keypair
         used as the identity for a hidden service.  This key is long
@@ -229,7 +230,10 @@ Public/private keypairs defined in this document:
         and [SUBCRED]. The public key is encoded in the ".onion"
         address according to [NAMING].
         KP_hs_id, KS_hs_id.
+```
 
+<a id="hs_blind_id"></a>
+```text
       Blinded signing key -- A keypair derived from the identity key,
         used to sign descriptor signing keys. It changes periodically for
         each service. Clients who know a 'credential' consisting of the
@@ -239,6 +243,10 @@ Public/private keypairs defined in this document:
         (see [SUBCRED]).
         KP_hs_blind_id, KS_hs_blind_id.
 
+```
+
+<a id="hs_desc_sign"></a>
+```text
       Descriptor signing key -- A key used to sign hidden service
         descriptors.  This is signed by blinded signing keys. Unlike
         blinded signing keys and master identity keys, the secret part
@@ -246,7 +254,10 @@ Public/private keypairs defined in this document:
         public part of this key is included in the unencrypted section
         of HS descriptors (see [DESC-OUTER]).
         KP_hs_desc_sign, KS_hs_desc_sign.
+```
 
+<a id="hs_ipt_sid"></a>
+```text
       Introduction point authentication key -- A short-term signing
         keypair used to identify a hidden service's session at a given
         introduction point. The service makes a fresh keypair for each
@@ -258,19 +269,27 @@ Public/private keypairs defined in this document:
         point. (previously called a "service key" in rend-spec.txt)
         KP_hs_ipt_sid, KS_hs_ipt_sid
         ("hidden service introduction point session id").
+```
 
+<a id="hss_ntor"></a>
+```text
       Introduction point encryption key -- A short-term encryption
         keypair used when establishing connections via an introduction
         point. Plays a role analogous to Tor nodes' onion keys. The service
         makes a fresh keypair for each introduction point.
         KP_hss_ntor, KS_hss_ntor.
+```
 
+<a id="hss_desc_enc"></a>
+```text
       Ephemeral descriptor encryption key -- A short-lived encryption
         keypair made by the service, and used to encrypt the inner layer
         of hidden service descriptors when client authentication is in
         use.
         KP_hss_desc_enc, KS_hss_desc_enc
+```
 
+```text
    Nonces defined in this document:
 
       N_hs_desc_enc -- a nonce used to derive keys to decrypt the inner
diff --git a/spec/tor-spec/relay-keys.md b/spec/tor-spec/relay-keys.md
index 8e2b955..6086819 100644
--- a/spec/tor-spec/relay-keys.md
+++ b/spec/tor-spec/relay-keys.md
@@ -45,7 +45,7 @@ is the same as the lifetime of the relay.
 
 Two identity keys are currently defined:
 
-- `KP_relayid_ed`, `KS_relayid_ed`:
+- <span id="relayid_ed">`KP_relayid_ed`, `KS_relayid_ed`:</span>
    An "ed25519 identity key",
    also sometimes called a "master identity key".
 
@@ -56,7 +56,7 @@ Two identity keys are currently defined:
    which is used to sign
    other important keys and objects.
 
-- `KP_relayid_rsa`, `KS_relayid_rsa`.
+- <span id="relayid_rsa">`KP_relayid_rsa`, `KS_relayid_rsa`:</span>
    A _legacy_ "RSA identity key".
 
    This is an RSA key.
@@ -79,13 +79,13 @@ Parties SHOULD NOT use the RSA identity on its own.
 We write `KP_relayid` to refer to a key which is either
 `KP_relayid_rsa` or `KP_relayid_ed`.
 
-## Online signing keys
+## Online signing keys {#online-signing}
 
 Since Tor's design tries to support
 keeping the high-value Ed25519 relay identity key offline,
 we need a corresponding key that can be used for online signing:
 
-- `KP_relaysign_ed`, `KS_relaysign_ed`:
+- <span id="relaysign_ed">`KP_relaysign_ed`, `KS_relaysign_ed`:</span>
   A medium-term Ed25519 "signing" key.
   This key is signed by the identity key `KP_relayid_ed`,
   and must be kept online.
@@ -94,6 +94,11 @@ we need a corresponding key that can be used for online signing:
   including directory objects,
   and certificates for other keys.
 
+When this key is generated,
+it needs to be signed with the `KP_relayid_ed` key,
+producing a [certificate of type `IDENTITY_V_SIGNING`](../cert-spec.md).
+The `KP_relayid_ed` key is not used for anything else.
+
 
 ## Circuit extension keys
 
@@ -120,13 +125,13 @@ after publishing any new key.
 
 There are two current kinds of circuit extension keys:
 
-- `KP_ntor`, `KS_ntor`:
+- <span id="ntor">`KP_ntor`, `KS_ntor`</span>:
   A curve25519 key
   used for the [`ntor`](./create-created-cells.md#ntor)
   and [`ntorv3`](./create-created-cells.md#ntor-v3)
   circuit extension handshakes.
 
-- `KP_onion_tap`, `KS_onion_tap`:
+- <span id="onion_tap">`KP_onion_tap`, `KS_onion_tap`</span>:
   A 1024 bit RSA key
   used for the obsolete [`TAP`](./create-created-cells.md#ntor)
   circuit extension handshake.
@@ -145,12 +150,12 @@ and SHOULD rotate them frequently—typically, at least once a day.
      handshake distinction. As it stands I'm not at all sure I can
      describe them correctly. -->
 
-- `KP_legacy_conn_tls`, `KS_legacy_conn_tls`:
+- <span id="legacy_conn_tls">`KP_legacy_conn_tls`, `KS_legacy_conn_tls`</span>:
   A short-term RSA "Connection key" used to negotiate TLS connections.
   Tor implementations MAY rotate this key as often as they like, and
   SHOULD rotate this key at least once a day.
 
-- `KP_link_ed`, `KS_link_ed`.
+- <span id="link_ed">`KP_link_ed`, `KS_link_ed`</span>.
   A short-term Ed25519 "link authentication" key, used to authenticate
   the link handshake: see
   ["Negotiating and initializing channels"](./negotiating-channels.md#negotiating).