diff options
Diffstat (limited to 'spec/rend-spec/introduction-protocol.md')
-rw-r--r-- | spec/rend-spec/introduction-protocol.md | 57 |
1 files changed, 52 insertions, 5 deletions
diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index 98e71a2..60e5a40 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -34,7 +34,7 @@ the introduction request to the client. <a id="rend-spec-v3.txt-3.1.1"></a> -### Extensible ESTABLISH_INTRO protocol. {#EST_INTRO} +### Extensible ESTABLISH_INTRO protocol {#EST_INTRO} When a hidden service is establishing a new introduction point, it sends an ESTABLISH_INTRO cell with the following contents: @@ -115,15 +115,17 @@ later in INTRODUCE1 cells. <a id="rend-spec-v3.txt-3.1.1.1"></a> -#### Denial-of-Service Defense Extension. {#EST_INTRO_DOS_EXT} +#### Denial-of-Service defense extension {#EST_INTRO_DOS_EXT} This extension can be used to send Denial-of-Service (DoS) parameters to the introduction point in order for it to apply them for the introduction circuit. +This is for the [rate limiting DoS mitigation](../dos-spec/overview.md#hs-intro-rate) specifically. + If used, it needs to be encoded within the N_EXTENSIONS field of the ESTABLISH_INTRO cell defined in the previous section. The content is -defined as follow: +defined as follows: EXT_FIELD_TYPE: @@ -240,7 +242,7 @@ apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.2"></a> -## Sending an INTRODUCE1 cell to the introduction point. {#SEND_INTRO1} +## Sending an INTRODUCE1 cell to the introduction point {#SEND_INTRO1} In order to participate in the introduction protocol, a client must know the following: @@ -267,7 +269,7 @@ or that its request will not succeed. <a id="rend-spec-v3.txt-3.2.1"></a> -### INTRODUCE1 cell format {#FMT_INTRO1} +### Extensible INTRODUCE1 cell format {#FMT_INTRO1} When a client is connecting to an introduction point, INTRODUCE1 cells should be of the form: @@ -310,6 +312,51 @@ 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 cell 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 cells 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 cell format. {#INTRO_ACK} |