[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] r13430: Add a bunch more code documentation; change the interface of (in tor/trunk: . src/or)
Author: nickm
Date: 2008-02-08 16:13:15 -0500 (Fri, 08 Feb 2008)
New Revision: 13430
Modified:
tor/trunk/
tor/trunk/ChangeLog
tor/trunk/src/or/buffers.c
tor/trunk/src/or/circuitbuild.c
tor/trunk/src/or/connection_edge.c
tor/trunk/src/or/connection_or.c
tor/trunk/src/or/networkstatus.c
tor/trunk/src/or/or.h
tor/trunk/src/or/rephist.c
Log:
r14063@tombo: nickm | 2008-02-08 15:48:32 -0500
Add a bunch more code documentation; change the interface of fetch_var_cell_from_buf() so it takes the current link protocol into account and can't get confused by weird command bytes on v1 connections.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r14063] on 49666b30-7950-49c5-bedf-9dc8f3168102
Modified: tor/trunk/ChangeLog
===================================================================
--- tor/trunk/ChangeLog 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/ChangeLog 2008-02-08 21:13:15 UTC (rev 13430)
@@ -59,6 +59,8 @@
on 0.1.2.x.
- Fix shell error when warning about missing packages in configure
script, on fedora or redhat machines. Bugfix on 0.2.0.x.
+ - Do not become confused when receiving a spurious VERSIONS-like
+ cell from a confused v1 client. Bugfix on 0.2.0.x.
o Code simplifications and refactoring:
- Remove some needless generality from cpuworker code, for improved
Modified: tor/trunk/src/or/buffers.c
===================================================================
--- tor/trunk/src/or/buffers.c 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/src/or/buffers.c 2008-02-08 21:13:15 UTC (rev 13430)
@@ -727,7 +727,12 @@
}
}
-/** DOCDOC */
+/** Helper for flush_buf_tls(): try to write <b>sz</b> bytes from chunk
+ * <b>chunk</b> of buffer <b>buf</b> onto socket <b>s</b>. (Tries to write
+ * more if there is a forced pending write size.) On success, deduct the
+ * bytes written from *<b>buf_flushlen</b>. Return the number of bytes
+ * written on success, and a TOR_TLS error code on failue or blocking.
+ */
static INLINE int
flush_chunk_tls(tor_tls_t *tls, buf_t *buf, chunk_t *chunk,
size_t sz, size_t *buf_flushlen)
@@ -799,8 +804,8 @@
return flushed;
}
-/** As flush_buf(), but writes data to a TLS connection.
- * DOCDOC can write more than flushlen bytes.
+/** As flush_buf(), but writes data to a TLS connection. Can write more than
+ * <b>flushlen</b> bytes.
*/
int
flush_buf_tls(tor_tls_t *tls, buf_t *buf, size_t flushlen,
@@ -918,15 +923,26 @@
return buf->datalen;
}
-/** DOCDOC Returns 0 on "not a var-length cell."; 1 whether it's all here
- * yet or not. */
+/** Check <b>buf</b> for a variable-length cell according to the rules of link
+ * protocol version <b>linkproto</b>. If one is found, pull it off the buffer
+ * and assign a newly allocated var_cell_t to *<b>out</b>, and return 1.
+ * Return 0 if whatever is on the start of buf_t is not a variable-length
+ * cell. Return 1 and set *<b>out</b> to NULL if there seems to be the start
+ * of a variable-length cell on <b>buf</b>, but the whole thing isn't there
+ * yet. */
int
-fetch_var_cell_from_buf(buf_t *buf, var_cell_t **out)
+fetch_var_cell_from_buf(buf_t *buf, var_cell_t **out, int linkproto)
{
char hdr[VAR_CELL_HEADER_SIZE];
var_cell_t *result;
uint8_t command;
uint16_t length;
+ /* If linkproto is unknown (0) or v2 (2), variable-length cells work as
+ * implemented here. If it's 1, there are no variable-length cells. Tor
+ * does not support other versions right now, and so can't negotiate them.
+ */
+ if (linkproto == 1)
+ return 0;
check();
*out = NULL;
if (buf->datalen < VAR_CELL_HEADER_SIZE)
Modified: tor/trunk/src/or/circuitbuild.c
===================================================================
--- tor/trunk/src/or/circuitbuild.c 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/src/or/circuitbuild.c 2008-02-08 21:13:15 UTC (rev 13430)
@@ -2822,7 +2822,7 @@
return 0;
}
-/** DOCDOC */
+/** DOCDOC arma */
typedef struct {
uint32_t addr;
uint16_t port;
Modified: tor/trunk/src/or/connection_edge.c
===================================================================
--- tor/trunk/src/or/connection_edge.c 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/src/or/connection_edge.c 2008-02-08 21:13:15 UTC (rev 13430)
@@ -1994,8 +1994,6 @@
* and call connection_ap_handshake_attach_circuit(conn) on it.
*
* Return the other end of the linked connection pair, or -1 if error.
- *
- * DOCDOC start_reading
*/
edge_connection_t *
connection_ap_make_link(char *address, uint16_t port,
@@ -2051,7 +2049,9 @@
return conn;
}
-/** DOCDOC */
+/** Notify any interested controller connections about a new hostname resolve
+ * or resolve error. Takes the same arguments as does
+ * connection_ap_handshake_socks_resolved(). */
static void
tell_controller_about_resolved_result(edge_connection_t *conn,
int answer_type,
@@ -2088,7 +2088,7 @@
* via SOCKS. The type should be one of RESOLVED_TYPE_(IPV4|IPV6|HOSTNAME) or
* -1 for unreachable; the answer should be in the format specified
* in the socks extensions document.
- * DOCDOC expires
+ * DOCDOC ttl expires
**/
void
connection_ap_handshake_socks_resolved(edge_connection_t *conn,
Modified: tor/trunk/src/or/connection_or.c
===================================================================
--- tor/trunk/src/or/connection_or.c 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/src/or/connection_or.c 2008-02-08 21:13:15 UTC (rev 13430)
@@ -152,7 +152,8 @@
memcpy(dest->payload, src+3, CELL_PAYLOAD_SIZE);
}
-/** DOCDOC */
+/** Write the header of <b>cell</b> into the first VAR_CELL_HEADER_SIZE
+ * bytes of <b>hdr_out</b>. */
void
var_cell_pack_header(const var_cell_t *cell, char *hdr_out)
{
@@ -161,7 +162,8 @@
set_uint16(hdr_out+3, htons(cell->payload_len));
}
-/* DOCDOC*/
+/** Allocate and return a new var_cell_t with <b>payload_len</b> bytes of
+ * payload space. */
var_cell_t *
var_cell_new(uint16_t payload_len)
{
@@ -172,7 +174,7 @@
return cell;
}
-/** DOCDOC */
+/** Release all space held by <b>cell</b> */
void
var_cell_free(var_cell_t *cell)
{
@@ -579,13 +581,17 @@
return 0;
}
-/*DOCDOC*/
+/** Invoked on the server side from inside tor_tls_read() when the server
+ * gets a successful TLS renegotiation from the client. */
static void
connection_or_tls_renegotiated_cb(tor_tls_t *tls, void *_conn)
{
or_connection_t *conn = _conn;
(void)tls;
+ /* Don't invoke this again. */
+ tor_tls_set_renegotiate_callback(tls, NULL, NULL);
+
if (connection_tls_finish_handshake(conn) < 0) {
/* XXXX_TLS double-check that it's ok to do this from inside read. */
/* XXXX_TLS double-check that this verifies certificates. */
@@ -937,7 +943,10 @@
conn->timestamp_last_added_nonpadding = time(NULL);
}
-/**DOCDOC*/
+/** Pack a variable-length <b>cell</b> into wire-format, and write it onto
+ * <b>conn</b>'s outbuf. Right now, this <em>DOES NOT</em> support cells that
+ * affect a circuit.
+ */
void
connection_or_write_var_cell_to_buf(const var_cell_t *cell,
or_connection_t *conn)
@@ -952,11 +961,12 @@
conn->timestamp_last_added_nonpadding = time(NULL);
}
-/** DOCDOC */
+/** See whether there's a variable-length cell waiting on <b>conn</b>'s
+ * inbuf. Return values as for fetch_var_cell_from_buf(). */
static int
connection_fetch_var_cell_from_buf(or_connection_t *conn, var_cell_t **out)
{
- return fetch_var_cell_from_buf(conn->_base.inbuf, out);
+ return fetch_var_cell_from_buf(conn->_base.inbuf, out, conn->link_proto);
}
/** Process cells from <b>conn</b>'s inbuf.
@@ -1026,12 +1036,14 @@
return 0;
}
-/**DOCDOC*/
+/** Array of recognized link protocol versions. */
static const uint16_t or_protocol_versions[] = { 1, 2 };
+/** Number of versions in <b>or_protocol_versions</b>. */
static const int n_or_protocol_versions =
sizeof(or_protocol_versions)/sizeof(uint16_t);
-/**DOCDOC*/
+/** Return true iff <b>v</b> is a link protocol version that this Tor
+ * implementation believes it can support. */
int
is_or_protocol_version_known(uint16_t v)
{
@@ -1043,7 +1055,8 @@
return 0;
}
-/** DOCDOC */
+/** Send a VERSIONS cell on <b>conn</b>, telling the other host about the
+ * link protocol versions that this Tor can support. */
static int
connection_or_send_versions(or_connection_t *conn)
{
@@ -1065,7 +1078,8 @@
return 0;
}
-/** DOCDOC */
+/** Send a NETINFO cell on <b>conn</b>, telling the other server what we know
+ * about their address, our address, and the current time. */
int
connection_or_send_netinfo(or_connection_t *conn)
{
Modified: tor/trunk/src/or/networkstatus.c
===================================================================
--- tor/trunk/src/or/networkstatus.c 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/src/or/networkstatus.c 2008-02-08 21:13:15 UTC (rev 13430)
@@ -784,7 +784,9 @@
}
/*XXXX make this static once functions are moved into this file. */
-/** DOCDOC */
+/** Search the routerstatuses in <b>ns</b> for one whose identity digest is
+ * <b>digest</b>. Return value and set *<b>found_out</b> as for
+ * smartlist_besearch_idx(). */
int
networkstatus_vote_find_entry_idx(networkstatus_t *ns,
const char *digest, int *found_out)
@@ -944,7 +946,8 @@
return strmap_get_lc(named_server_map, nickname);
}
-/** DOCDOC */
+/** Return true iff <b>nickname</b> is disallowed from being the nickname
+ * of any server. */
int
networkstatus_nickname_is_unnamed(const char *nickname)
{
@@ -1020,9 +1023,10 @@
}
}
-/**DOCDOC*/
+/** How many times will we try to fetch a consensus before we give up? */
#define CONSENSUS_NETWORKSTATUS_MAX_DL_TRIES 8
-/**DOCDOC*/
+/** How long will we hang onto a possibly live consensus for which we're
+ * fetching certs before we check whether there is a better one? */
#define DELAY_WHILE_FETCHING_CERTS (20*60)
/** If we want to download a fresh consensus, launch a new download as
@@ -1045,6 +1049,7 @@
return; /* There's an in-progress download.*/
if (consensus_waiting_for_certs) {
+ /* XXXX020 make sure this doesn't delay sane downloads. */
if (consensus_waiting_for_certs_set_at + DELAY_WHILE_FETCHING_CERTS > now)
return; /* We're still getting certs for this one. */
else {
@@ -1070,7 +1075,8 @@
update_consensus_networkstatus_downloads(time(NULL));
}
-/**DOCDOC*/
+/** How long do we (as a cache) wait after a consensus becomes non-fresh
+ * before trying to fetch another? */
#define CONSENSUS_MIN_SECONDS_BEFORE_CACHING 120
/** Update the time at which we'll consider replacing the current
@@ -1160,7 +1166,8 @@
update_certificate_downloads(now);
}
-/**DOCDOC */
+/** Launch requests as appropriate for missing directory authority
+ * certificates. */
void
update_certificate_downloads(time_t now)
{
@@ -1206,7 +1213,8 @@
/* XXXX020 remove this in favor of get_live_consensus. But actually,
* leave something like it for bridge users, who need to not totally
* lose if they spend a while fetching a new consensus. */
-/** DOCDOC */
+/** As networkstatus_get_live_consensus(), but is way more tolerant of expired
+ * consensuses. */
networkstatus_t *
networkstatus_get_reasonably_live_consensus(time_t now)
{
@@ -1751,7 +1759,8 @@
router_dir_info_changed();
}
-/**DOCDOC*/
+/** Given a list of signed_descriptor_t, update their fields (mainly, when
+ * they were last listed) from the most recent consensus. */
void
signed_descs_update_status_from_consensus_networkstatus(smartlist_t *descs)
{
Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/src/or/or.h 2008-02-08 21:13:15 UTC (rev 13430)
@@ -245,14 +245,17 @@
#define OR_CONN_STATE_PROXY_FLUSHING 2
/** State for a connection to an OR: waiting for proxy response. */
#define OR_CONN_STATE_PROXY_READING 3
-/** State for a connection to an OR: SSL is handshaking, not done yet. */
+/** State for a connection to an OR or client: SSL is handshaking, not done
+ * yet. */
#define OR_CONN_STATE_TLS_HANDSHAKING 4
-/** DOCDOC */
+/** State for a connection to an OR: We're doing a second SSL handshake for
+ * renegotiation purposes. */
#define OR_CONN_STATE_TLS_CLIENT_RENEGOTIATING 5
-/** DOCDOC */
+/** State for a connection at an OR: We're waiting for the client to
+ * renegotiate. */
#define OR_CONN_STATE_TLS_SERVER_RENEGOTIATING 6
/** State for a connection to an OR: We're done with our SSL handshake, but we
- * haven't yet negotiated link protocol versions and finished authenticating.
+ * haven't yet negotiated link protocol versions and sent a netinfo cell.
*/
#define OR_CONN_STATE_OR_HANDSHAKING 7
/** State for a connection to an OR: Ready to send/receive cells. */
@@ -2457,7 +2460,7 @@
const char *data, size_t data_len, int done);
int move_buf_to_buf(buf_t *buf_out, buf_t *buf_in, size_t *buf_flushlen);
int fetch_from_buf(char *string, size_t string_len, buf_t *buf);
-int fetch_var_cell_from_buf(buf_t *buf, var_cell_t **out);
+int fetch_var_cell_from_buf(buf_t *buf, var_cell_t **out, int linkproto);
int fetch_from_buf_http(buf_t *buf,
char **headers_out, size_t max_headerlen,
char **body_out, size_t *body_used, size_t max_bodylen,
Modified: tor/trunk/src/or/rephist.c
===================================================================
--- tor/trunk/src/or/rephist.c 2008-02-08 21:13:12 UTC (rev 13429)
+++ tor/trunk/src/or/rephist.c 2008-02-08 21:13:15 UTC (rev 13430)
@@ -19,8 +19,9 @@
static void predicted_ports_init(void);
static void hs_usage_init(void);
-/**DOCDOC*/
+/** Total number of bytes currently allocated in fields used by rephist.c */
uint64_t rephist_total_alloc=0;
+/** Number of or_history_t obects currently allocated */
uint32_t rephist_total_num=0;
/** If the total weighted run count of all runs for a router ever falls