Merge branch 'hs-pow-intro-ext' into 'main'

Revise the INTRO1_POW_EXT section

See merge request tpo/core/torspec!253

1 files changed, 31 insertions, 72 deletions

diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md
index fe59a1d..02ed828 100644
--- a/spec/rend-spec/introduction-protocol.md
+++ b/spec/rend-spec/introduction-protocol.md
@@ -341,52 +341,6 @@ client.)
 The same rules for multiplicity, ordering, and handling unknown types
 apply to the extension fields here as described \[EST_INTRO\] above.
 
-#### Proof-of-work extension to INTRODUCE1 {#INTRO1_POW_EXT}
-
-This extension can be used to optionally attach a proof of work to the introduction request.
-The proof must be calculated using unique parameters appropriate for this specific service.
-An acceptable proof will raise the priority of this introduction request according to the proof's verified computational effort.
-
-This is for the [proof-of-work DoS mitigation](../dos-spec/overview.md#hs-intro-pow), described in depth by the [Proof of Work for onion service introduction](../hspow-spec/index.md) specification.
-
-If used, it needs to be encoded within the N_EXTENSIONS field of the
-ESTABLISH_INTRO message defined in the previous section. The content is
-defined as follows:
-
-EXT_FIELD_TYPE:
-
-\[02\] -- `PROOF_OF_WORK`
-
-```text
-The EXT_FIELD content format is:
-
-    POW_VERSION    [1 byte]
-    POW_NONCE      [16 bytes]
-    POW_EFFORT     [4 bytes]
-    POW_SEED       [4 bytes]
-    POW_SOLUTION   [16 bytes]
-
-where:
-
-POW_VERSION is 1 for the 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
-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.
-
-This will increase the INTRODUCE1 message body size by 43 bytes
-since the extension type and length is 2 extra bytes, the N_EXTENSIONS field is always present and currently set to 0 and the EXT_FIELD is 41 bytes.
-According to ticket #33650, INTRODUCE1 messages currently have more than 200 bytes available.
-
-Introduced in tor-0.4.8.1-alpha.
-
 <a id="rend-spec-v3.txt-3.2.2"></a>
 
 ### INTRODUCE_ACK message format. {#INTRO_ACK}
@@ -531,43 +485,48 @@ descriptor. The client SHOULD NOT provide this field if the consensus parameter
 
 The service MUST ignore any unknown fields.
 
-#### Proof-of-Work (PoW)
+#### Proof-of-Work (PoW) {#INTRO1_POW_EXT}
 
-This is used to send the work done by the client to the service.
+This extension can be used to optionally attach a proof of work to the introduction request.
+The proof must be calculated using unique parameters appropriate for this specific service.
+An acceptable proof will raise the priority of this introduction request according to the proof's verified computational effort.
 
-   EXT_FIELD_TYPE:
+This is for the [proof-of-work DoS mitigation](../dos-spec/overview.md#hs-intro-pow), described in depth by the [Proof of Work for onion service introduction](../hspow-spec/index.md) specification.
 
-     \[02\] -- Proof Of Work.
+If used, it needs to be encoded within the N_EXTENSIONS field of the
+encrypted portion of the INTRO1/INTRO2 message. (After RENDEZVOUS_COOKIE and before ONION_KEY_TYPE)
 
-   EXT_FIELD content format is:
+The content is defined as follows:
 
-     POW_VERSION    [1 byte]
-     POW_NONCE      [16 bytes]
-     POW_EFFORT     [4 bytes]
-     POW_SEED       [4 bytes]
-     POW_SOLUTION   [16 bytes]
+EXT_FIELD_TYPE:
 
-   where:
+\[02\] -- `PROOF_OF_WORK`
 
-     POW_VERSION is 1 for the protocol specified in this proposal
-     POW_NONCE is the nonce 'N' from the section above
-     POW_EFFORT is the 32-bit integer effort value, in network byte order
-     POW_SEED is the first 4 bytes of the seed used
+```text
+The EXT_FIELD content format is:
 
+    POW_VERSION    [1 byte]
+    POW_NONCE      [16 bytes]
+    POW_EFFORT     [4 bytes]
+    POW_SEED       [4 bytes]
+    POW_SOLUTION   [16 bytes]
 
-When a service receives an INTRODUCE1 with the extension, it should check its
-configuration on whether proof-of-work is enabled on the service. If it's not
-enabled, the extension SHOULD be ignored. If enabled, even if the suggested
-effort is currently zero, the service follows the procedure detailed in
-prop327.
+where:
 
-If the service requires the PROOF_OF_WORK extension but received an INTRODUCE1
-message without any embedded proof-of-work, the service SHOULD consider this message
-as a zero-effort introduction for the purposes of the priority queue (see
-section \[INTRO_QUEUE\] of prop327).
+POW_VERSION is 1 for the 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
+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.
 
-(TODO: We should have a proof-of-work.md to fold in prop327. For now, just
-point to the proposal.)
+Introduced in tor-0.4.8.1-alpha.
 
 #### Subprotocol Request