aboutsummaryrefslogtreecommitdiff
path: root/spec/rend-spec/introduction-protocol.md
diff options
context:
space:
mode:
Diffstat (limited to 'spec/rend-spec/introduction-protocol.md')
-rw-r--r--spec/rend-spec/introduction-protocol.md57
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}