[tor-commits] [tor/master] Complete all DOCDOC entries from the ntor branch
nickm at torproject.org
nickm at torproject.org
Thu Jan 3 16:52:58 UTC 2013
commit 94cb7bd24d2ffda9038c267b3ee0837dd64ec903
Author: Nick Mathewson <nickm at torproject.org>
Date: Tue Dec 25 22:38:20 2012 -0500
Complete all DOCDOC entries from the ntor branch
---
src/or/circuitbuild.c | 8 ++++----
src/or/cpuworker.c | 21 ++++++++++++++++++---
src/or/onion.c | 5 ++---
src/or/onion_fast.c | 5 +++--
src/or/router.c | 36 ++++++++++++++++++------------------
5 files changed, 45 insertions(+), 30 deletions(-)
diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c
index 9300b04..552167f 100644
--- a/src/or/circuitbuild.c
+++ b/src/or/circuitbuild.c
@@ -490,10 +490,10 @@ circuit_n_chan_done(channel_t *chan, int status)
/** Find a new circid that isn't currently in use on the circ->n_chan
* for the outgoing
- * circuit <b>circ</b>, and deliver a cell of type <b>cell_type</b>
- * (either CELL_CREATE or CELL_CREATE_FAST) with payload <b>payload</b>
- * to this circuit. DOCDOC new arguments
- * Return -1 if we failed to find a suitable circid, else return 0.
+ * circuit <b>circ</b>, and deliver the cell <b>create_cell</b> to this
+ * circuit. If <b>relayed</b> is true, this is a create cell somebody
+ * gave us via an EXTEND cell, so we shouldn't worry if we don't understand
+ * it. Return -1 if we failed to find a suitable circid, else return 0.
*/
static int
circuit_deliver_create_cell(circuit_t *circ, const create_cell_t *create_cell,
diff --git a/src/or/cpuworker.c b/src/or/cpuworker.c
index 1ac8cd5..3f8fc94 100644
--- a/src/or/cpuworker.c
+++ b/src/or/cpuworker.c
@@ -84,29 +84,44 @@ tag_unpack(const uint8_t *tag, uint64_t *chan_id, circid_t *circ_id)
*circ_id = get_uint16(tag+8);
}
-/** DOCDOC */
+/** Magic numbers to make sure our cpuworker_requests don't grow any
+ * mis-framing bugs. */
#define CPUWORKER_REQUEST_MAGIC 0xda4afeed
#define CPUWORKER_REPLY_MAGIC 0x5eedf00d
-/**DOCDOC*/
+/** A request sent to a cpuworker. */
typedef struct cpuworker_request_t {
+ /** Magic number; must be CPUWORKER_REQUEST_MAGIC. */
uint32_t magic;
/** Opaque tag to identify the job */
uint8_t tag[TAG_LEN];
+ /** Task code. Must be one of CPUWORKER_TASK_* */
uint8_t task;
+ /** A create cell for the cpuworker to process. */
create_cell_t create_cell;
+
/* Turn the above into a tagged union if needed. */
} cpuworker_request_t;
-/**DOCDOC*/
+/** A reply sent by a cpuworker. */
typedef struct cpuworker_reply_t {
+ /** Magic number; must be CPUWORKER_REPLY_MAGIC. */
uint32_t magic;
+ /** Opaque tag to identify the job; matches the request's tag.*/
uint8_t tag[TAG_LEN];
+ /** True iff we got a successful request. */
uint8_t success;
+ /** Output of processing a create cell
+ *
+ * @{
+ */
+ /** The created cell to send back. */
created_cell_t created_cell;
+ /** The keys to use on this circuit. */
uint8_t keys[CPATH_KEY_MATERIAL_LEN];
+ /** Input to use for authenticating introduce1 cells. */
uint8_t rend_auth_material[DIGEST_LEN];
} cpuworker_reply_t;
diff --git a/src/or/onion.c b/src/or/onion.c
index 56bc9a3..fc3e621 100644
--- a/src/or/onion.c
+++ b/src/or/onion.c
@@ -304,9 +304,8 @@ onion_skin_create(int type,
* type <b>type</b>, responding to the client request in <b>onion_skin</b>
* using the keys in <b>keys</b>. On success, write our response into
* <b>reply_out</b>, generate <b>keys_out_len</b> bytes worth of key material
- * in <b>keys_out_len</b>, and return the length of the reply. On failure,
- * return -1.
- * DOCDOC rend_nonce_out
+ * in <b>keys_out_len</b>, a hidden service nonce to <b>rend_nonce_out</b>,
+ * and return the length of the reply. On failure, return -1.
*/
int
onion_skin_server_handshake(int type,
diff --git a/src/or/onion_fast.c b/src/or/onion_fast.c
index f33b048..eb9eceb 100644
--- a/src/or/onion_fast.c
+++ b/src/or/onion_fast.c
@@ -12,7 +12,7 @@
#include "or.h"
#include "onion_fast.h"
-/**DOCDOC*/
+/** Release all state held in <b>victim</b>. */
void
fast_handshake_state_free(fast_handshake_state_t *victim)
{
@@ -22,7 +22,8 @@ fast_handshake_state_free(fast_handshake_state_t *victim)
tor_free(victim);
}
-/** DOCDOC */
+/** Create the state needed to perform a CREATE_FAST hasnshake. Return 0
+ * on success, -1 on failure. */
int
fast_onionskin_create(fast_handshake_state_t **handshake_state_out,
uint8_t *handshake_out)
diff --git a/src/or/router.c b/src/or/router.c
index a97db85..961fd48 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -56,8 +56,10 @@ static crypto_pk_t *onionkey=NULL;
* generated by clients that have an older version of our descriptor. */
static crypto_pk_t *lastonionkey=NULL;
#ifdef CURVE25519_ENABLED
-/**DOCDOC*/
+/** Current private ntor secret key: used to perform the ntor handshake. */
static curve25519_keypair_t curve25519_onion_key;
+/** Previous private ntor secret key: used to perform the ntor handshake
+ * with clients that have an older version of our descriptor. */
static curve25519_keypair_t last_curve25519_onion_key;
#endif
/** Private server "identity key": used to sign directory info and TLS
@@ -105,20 +107,6 @@ set_onion_key(crypto_pk_t *k)
mark_my_descriptor_dirty("set onion key");
}
-#if 0
-/**DOCDOC*/
-static void
-set_curve25519_onion_key(const curve25519_keypair_t *kp)
-{
- if (tor_memeq(&curve25519_onion_key, kp, sizeof(curve25519_keypair_t)))
- return;
-
- tor_mutex_acquire(key_lock);
- memcpy(&curve25519_onion_key, kp, sizeof(curve25519_keypair_t));
- tor_mutex_release(key_lock);
-}
-#endif
-
/** Return the current onion key. Requires that the onion key has been
* loaded or generated. */
crypto_pk_t *
@@ -147,12 +135,15 @@ dup_onion_keys(crypto_pk_t **key, crypto_pk_t **last)
}
#ifdef CURVE25519_ENABLED
-/**DOCDOC only in main thread*/
+/** Return the current secret onion key for the ntor handshake. Must only
+ * be called from the main thread. */
static const curve25519_keypair_t *
get_current_curve25519_keypair(void)
{
return &curve25519_onion_key;
}
+/** Return a map from KEYID (the key itself) to keypairs for use in the ntor
+ * handshake. Must only be called from the main thread. */
di_digest256_map_t *
construct_ntor_key_map(void)
{
@@ -173,6 +164,8 @@ construct_ntor_key_map(void)
return m;
}
+/** Helper used to deallocate a di_digest256_map_t returned by
+ * construct_ntor_key_map. */
static void
ntor_key_map_free_helper(void *arg)
{
@@ -180,9 +173,12 @@ ntor_key_map_free_helper(void *arg)
memwipe(k, 0, sizeof(*k));
tor_free(k);
}
+/** Release all storage from a keymap returned by construct_ntor_key_map. */
void
ntor_key_map_free(di_digest256_map_t *map)
{
+ if (!map)
+ return;
dimap_free(map, ntor_key_map_free_helper);
}
#endif
@@ -453,7 +449,11 @@ init_key_from_file(const char *fname, int generate, int severity)
}
#ifdef CURVE25519_ENABLED
-/** DOCDOC */
+/** Load a curve25519 keypair from the file <b>fname</b>, writing it into
+ * <b>keys_out</b>. If the file isn't found and <b>generate</b> is true,
+ * create a new keypair and write it into the file. If there are errors, log
+ * them at level <b>severity</b>. Generate files using <b>tag</b> in their
+ * ASCII wrapper. */
static int
init_curve25519_keypair_from_file(curve25519_keypair_t *keys_out,
const char *fname,
@@ -1599,7 +1599,7 @@ router_digest_is_me(const char *digest)
tor_memeq(server_identitykey_digest, digest, DIGEST_LEN));
}
-/** DOCDOC */
+/** Return my identity digest. */
const uint8_t *
router_get_my_id_digest(void)
{
More information about the tor-commits
mailing list