Merge branch 'hspow' into 'main'

hspow: Clarifications to scheme and descriptor Item

See merge request tpo/core/torspec!254

3 files changed, 19 insertions, 13 deletions

diff --git a/spec/hspow-spec/v1-equix.md b/spec/hspow-spec/v1-equix.md
index 025af48..f49086a 100644
--- a/spec/hspow-spec/v1-equix.md
+++ b/spec/hspow-spec/v1-equix.md
@@ -1,4 +1,4 @@
-# Onion service proof-of-work: Version 1, Equi-X and Blake2b
+# Onion service proof-of-work: Scheme v1, Equi-X and Blake2b
 
 ## Implementations {#implementations}
 
@@ -82,7 +82,7 @@ Thus the effort is communicated explicitly in our protocol, and it forms part of
 ## Parameter descriptor {#parameter-descriptor}
 
 This whole protocol starts with the service encoding its parameters in a `pow-params` line within the 'encrypted' (inner) part of the v3 descriptor. The [second layer plaintext format](../rend-spec/hsdesc-encrypt.md#second-layer-plaintext) describes it canonically. The parameters offered are:
-- `type`, always `v1` for the algorithm described here
+- `scheme`, always `v1` for the algorithm described here
 - `seed-b64`, a periodically updated 32-byte random seed, base64 encoded
 - `suggested-effort`, the latest output from the [service-side effort controller](./common-protocol.md#service-effort)
 - `expiration-time`, a timestamp when we plan to replace the seed.
diff --git a/spec/rend-spec/hsdesc-encrypt.md b/spec/rend-spec/hsdesc-encrypt.md
index 3e91172..531c70a 100644
--- a/spec/rend-spec/hsdesc-encrypt.md
+++ b/spec/rend-spec/hsdesc-encrypt.md
@@ -252,21 +252,23 @@ list of intro points etc. The plaintext has the following format:
 ```
 
 ```text
-     "pow-params" SP type SP seed-b64 SP suggested-effort
+     "pow-params" SP scheme SP seed-b64 SP suggested-effort
                   SP expiration-time NL
 
-      [At most once per "type"]
+      [At most once per "scheme"]
 
       If present, this line provides parameters for an optional proof-of-work
       client puzzle. A client that supports an offered scheme can include a
       corresponding solution in its introduction request to improve priority
       in the service's processing queue.
 
-      Only version 1 is currently defined.
-      Other versions may have a different format.
+      Only scheme `v1` is currently defined.
+      Unknown schemes found in a descriptor should be ignored by clients.
+      Other schemes may have a different format (in the parts of the
+      Item after the "scheme"; this could even include an Object).
       Introduced in tor-0.4.8.1-alpha.
 
-        type: The type of PoW system used. We call the one specified here "v1".
+        scheme: The PoW system used. We call the one specified here "v1".
 
         seed-b64: A random seed that should be used as the input to the PoW
                   hash function. Should be 32 random bytes encoded in base64
diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md
index 02ed828..829ba98 100644
--- a/spec/rend-spec/introduction-protocol.md
+++ b/spec/rend-spec/introduction-protocol.md
@@ -505,7 +505,7 @@ EXT_FIELD_TYPE:
 ```text
 The EXT_FIELD content format is:
 
-    POW_VERSION    [1 byte]
+    POW_SCHEME     [1 byte]
     POW_NONCE      [16 bytes]
     POW_EFFORT     [4 bytes]
     POW_SEED       [4 bytes]
@@ -513,7 +513,7 @@ The EXT_FIELD content format is:
 
 where:
 
-POW_VERSION is 1 for the protocol specified here
+POW_SCHEME is 1 for the `v1` protocol specified here
 POW_NONCE is the nonce value chosen by the client's solver
 POW_EFFORT is the effort value chosen by the client,
            as a 32-bit integer in network byte order
@@ -521,10 +521,14 @@ POW_SEED identifies which seed was in use, by its first 4 bytes
 POW_SOLUTION is a matching proof computed by the client's solver
 ```
 
-Only version 1 is currently defined.
-Other versions may have a different format.
-A correctly functioning client only submits solutions with a version and seed which were advertised by the server and have not yet expired.
-An extension with an unknown version or expired seed is suspicious and SHOULD result in introduction failure.
+Only SCHEME 1, `v1`, is currently defined.
+Other schemes may have a different format,
+after the POW_SCHEME byte.
+A correctly functioning client only submits solutions with a scheme and seed which were advertised by the server
+(using a "pow-params" Item in the
+[HS descriptor](hsdesc-encrypt.md#second-layer-plaintext))
+and have not yet expired.
+An extension with an unknown scheme or expired seed is suspicious and SHOULD result in introduction failure.
 
 Introduced in tor-0.4.8.1-alpha.