Merge branch 'certs-revision' into 'main'

Revise cert-spec

See merge request tpo/core/torspec!221

3 files changed, 53 insertions, 3 deletions

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