diff options
-rw-r--r-- | spec/hspow-spec/v1-equix.md | 4 | ||||
-rw-r--r-- | spec/rend-spec/hsdesc-encrypt.md | 12 | ||||
-rw-r--r-- | spec/rend-spec/introduction-protocol.md | 16 |
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. |