commit 94cb7bd24d2ffda9038c267b3ee0837dd64ec903 Author: Nick Mathewson <nickm@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) {