From 9fedec9a1ebbb18d08334d7edf0e17b0a458b6fd Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 5 Mar 2024 11:49:02 +0000 Subject: hspow: Use consistent terminology for hspow schemes The text uses "scheme" and "version" a couple of times. The formal protocol says "type". The terminology should be consistent. IMO "scheme" is the best word to use. "version" is particularly bad. Change all references to "type" and "version" to "scheme". --- spec/hspow-spec/v1-equix.md | 4 ++-- spec/rend-spec/hsdesc-encrypt.md | 10 +++++----- 2 files changed, 7 insertions(+), 7 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..86abfae 100644 --- a/spec/rend-spec/hsdesc-encrypt.md +++ b/spec/rend-spec/hsdesc-encrypt.md @@ -252,21 +252,21 @@ 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. + Other schemes may have a different format. 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 -- cgit v1.2.3-54-g00ecf From 8e2b91f183c8f10ba9d00d33d121f4ffbc5e140b Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 5 Mar 2024 11:56:15 +0000 Subject: Specify client behaviour for unknown hspow schemes. --- spec/rend-spec/hsdesc-encrypt.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/rend-spec/hsdesc-encrypt.md b/spec/rend-spec/hsdesc-encrypt.md index 86abfae..48b5f24 100644 --- a/spec/rend-spec/hsdesc-encrypt.md +++ b/spec/rend-spec/hsdesc-encrypt.md @@ -263,6 +263,7 @@ list of intro points etc. The plaintext has the following format: in the service's processing queue. Only scheme `v1` is currently defined. + Unknown schemes found in a descriptor should be ignored by clients. Other schemes may have a different format. Introduced in tor-0.4.8.1-alpha. -- cgit v1.2.3-54-g00ecf From b002913adfa8cb717e46c77fd5375d0c80ee0a53 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 5 Mar 2024 12:09:44 +0000 Subject: Explain precisely how a pow-params might vary by scheme --- spec/rend-spec/hsdesc-encrypt.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/rend-spec/hsdesc-encrypt.md b/spec/rend-spec/hsdesc-encrypt.md index 48b5f24..531c70a 100644 --- a/spec/rend-spec/hsdesc-encrypt.md +++ b/spec/rend-spec/hsdesc-encrypt.md @@ -264,7 +264,8 @@ list of intro points etc. The plaintext has the following 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. + 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. scheme: The PoW system used. We call the one specified here "v1". -- cgit v1.2.3-54-g00ecf From 4cedc4751fac1dc76848f25d5482ccd5057b7d60 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 5 Mar 2024 15:44:51 +0000 Subject: Use "scheme" terminology in INTRODUCE1 pow --- spec/rend-spec/introduction-protocol.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index 02ed828..8cc18f6 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,10 @@ 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. +A correctly functioning client only submits solutions with a scheme and seed which were advertised by the server 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. -- cgit v1.2.3-54-g00ecf From 4ef958b071429e46edf05d7ac3fe0f17a06601a2 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 5 Mar 2024 15:45:13 +0000 Subject: Scheme: clarify where scheme variation occurs --- spec/rend-spec/introduction-protocol.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index 8cc18f6..aa01268 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -522,7 +522,8 @@ POW_SOLUTION is a matching proof computed by the client's solver ``` Only SCHEME 1, `v1`, is currently defined. -Other schemes may have a different format. +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 and have not yet expired. An extension with an unknown scheme or expired seed is suspicious and SHOULD result in introduction failure. -- cgit v1.2.3-54-g00ecf From a2b1828178afde1904b248b62e854cf1f4daf27c Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 5 Mar 2024 15:50:03 +0000 Subject: Cross reference from INTRODUCE1 to pow-params --- spec/rend-spec/introduction-protocol.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index aa01268..829ba98 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -524,7 +524,10 @@ POW_SOLUTION is a matching proof computed by the client's solver 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 and have not yet expired. +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. -- cgit v1.2.3-54-g00ecf