diff options
Diffstat (limited to 'spec/rend-spec/introduction-protocol.md')
| -rw-r--r-- | spec/rend-spec/introduction-protocol.md | 131 |
1 files changed, 53 insertions, 78 deletions
diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index cb7debf..43c5638 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -185,7 +185,7 @@ and the introduction point should ignore the other parameter. If the burst is lower than the rate, the introduction point SHOULD ignore the extension. -> Using this extension extends the payload of the ESTABLISH_INTRO message by 19 +> Using this extension extends the body of the ESTABLISH_INTRO message by 19 > bytes bringing it from 134 bytes to 155 bytes. When this extension is not _sent_, @@ -219,7 +219,7 @@ In this older protocol, an ESTABLISH_INTRO message contains: KEY_LEN [2 bytes] KEY [KEY_LEN bytes] HANDSHAKE_AUTH [20 bytes] - SIG [variable, up to end of relay payload] + SIG [variable, up to end of relay message body] The KEY_LEN variable determines the length of the KEY field. ``` @@ -313,7 +313,7 @@ should be of the form: EXT_FIELD_TYPE [1 byte] EXT_FIELD_LEN [1 byte] EXT_FIELD [EXT_FIELD_LEN bytes] - ENCRYPTED [Up to end of relay payload] + ENCRYPTED [Up to end of relay message body] ``` The `ENCRYPTED` field is described in the \[PROCESS_INTRO2\] section. @@ -341,51 +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 payload 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} @@ -508,10 +463,22 @@ will have: The same rules for multiplicity, ordering, and handling unknown types apply to the extension fields here as described \[EST_INTRO\] above. -### INTRODUCE1 Extensions +### INTRODUCE1/INTRODUCE2 Extensions The following sections details the currently supported or reserved extensions -of an `INTRODUCE1` message. +of an `INTRODUCE1`/`INTRODUCE2` message. + +Note that there are two sets of extensions in `INTRODUCE1`/`INTRODUCE2`: +one in the top-level, unencrypted portion, +and one within the plaintext of ENCRYPTED +(ie, after RENDEZVOUS_COOKIE and before ONION_KEY_TYPE. + +The sets of extensions allowed in each part of the message are disjoint: +each extension is valid in only *one* of the two places. + +Nevertheless, for historical reasons, +both kinds of extension are listed in this section, +and they use nonoverlapping values of `EXT_FIELD_TYPE`. #### Congestion Control @@ -522,51 +489,59 @@ configured with congestion control. \[01\] -- Congestion Control Request. -This field is has zero payload length. Its presence signifies that the client +This field is has zero body length. Its presence signifies that the client wants to use congestion control. The client MUST NOT set this field, or use ntorv3, if the service did not list "2" in the `FlowCtrl` line in the descriptor. The client SHOULD NOT provide this field if the consensus parameter 'cc_alg' is 0. -The service MUST ignore any unknown fields. +This appears in the ENCRYPTED section of the INTRODUCE1/INTRODUCE2 message. -#### 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. +This appears in the ENCRYPTED section of the INTRODUCE1/INTRODUCE2 message. - 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_SCHEME [1 byte] + POW_NONCE [16 bytes] + POW_EFFORT [4 bytes] + POW_SEED [4 bytes] + POW_SOLUTION [16 bytes] + +where: -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. +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 +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 +``` -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). +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. -(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 |