From: teor <teor@torproject.org>
Date: Tue, 17 Mar 2020 07:41:26 +0000 (+1000)
Subject: relay: Improve the comments on onionskin_answer()
X-Git-Tag: tor-0.4.5.0-alpha-dev~60^2~25
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=beee9ca608e860ee71446e4923bf4f673eb012e3;p=thirdparty%2Ftor.git

relay: Improve the comments on onionskin_answer()

Part of 33633.
---

diff --git a/src/feature/relay/circuitbuild_relay.c b/src/feature/relay/circuitbuild_relay.c
index 9da89953fb..85a05a8651 100644
--- a/src/feature/relay/circuitbuild_relay.c
+++ b/src/feature/relay/circuitbuild_relay.c
@@ -193,8 +193,24 @@ circuit_extend(struct cell_t *cell, struct circuit_t *circ)
   return 0;
 }
 
-/** Given a response payload and keys, initialize, then send a created
- * cell back.
+/** On a relay, accept a create cell, initialise a circuit, and send a
+ * created cell back.
+ *
+ * Given:
+ *   - a response payload consisting of:
+ *     - the <b>created_cell</b> and
+ *     - an optional <b>rend_circ_nonce</b>, and
+ *   - <b>keys</b> of length <b>keys_len</b>, which must be
+ *     CPATH_KEY_MATERIAL_LEN;
+ * then:
+ *   - initialize the circuit <b>circ</b>'s cryptographic material,
+ *   - set the circuit's state to open, and
+ *   - send a created cell back on that circuit.
+ *
+ * If we haven't found our ORPorts reachable yet, and the channel meets the
+ * necessary conditions, mark the relevant ORPorts as reachable.
+ *
+ * Returns -1 if cell or circuit initialisation fails.
  */
 int
 onionskin_answer(struct or_circuit_t *circ,