[or-cvs] r11255: Add some voting-related documentation. (in tor/trunk: . src/or)
nickm at seul.org
nickm at seul.org
Wed Aug 22 15:07:44 UTC 2007
Author: nickm
Date: 2007-08-22 11:07:44 -0400 (Wed, 22 Aug 2007)
New Revision: 11255
Modified:
tor/trunk/
tor/trunk/src/or/dirserv.c
tor/trunk/src/or/dirvote.c
Log:
r14185 at Kushana: nickm | 2007-08-22 11:07:01 -0400
Add some voting-related documentation.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r14185] on c95137ef-5f19-0410-b913-86e773d04f59
Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c 2007-08-22 15:07:29 UTC (rev 11254)
+++ tor/trunk/src/or/dirserv.c 2007-08-22 15:07:44 UTC (rev 11255)
@@ -1089,7 +1089,7 @@
* cached_dir_t. */
static digestmap_t *cached_v2_networkstatus = NULL;
-/** DOCDOC */
+/** The v3 consensus network status that we're currently serving. */
static cached_dir_t *cached_v3_networkstatus = NULL;
/** Possibly replace the contents of <b>d</b> with the value of
@@ -1258,7 +1258,9 @@
}
}
-/* DOCDOC */
+/** Replace the v3 consensus networkstatus that we're serving with
+ * <b>networkstatus</b>, published at <b>published</b>. No validation is
+ * performed. */
void
dirserv_set_cached_networkstatus_v3(const char *networkstatus,
time_t published)
@@ -1788,9 +1790,10 @@
DIGEST_LEN);
}
-/** DOCDOC
- *
- * sort first by addr, and then by descending order of usefulness.
+/** Helper for sorting: compares two routerinfos first by address, and then by
+ * descending order of "usefulness". (An authority is more useful than a
+ * non-authority; a running router is more useful than a non-running router;
+ * and a router with more bandwidth is more useful than one with less.)
**/
static int
_compare_routerinfo_by_ip_and_bw(const void **a, const void **b)
@@ -1806,10 +1809,9 @@
else if (first->addr > second->addr)
return 1;
- /* XXX020 k n lg n memcmps could show up bigtime in profiling. If
- * they do, I suggest we just give authorities a free pass. -RD */
- /* I think we're fine. Remember, in nearly all cases, the addresses
- * will be different and we'll never actually reach this point. -NM */
+ /* Potentially, this next bit could cause k n lg n memcmp calls. But in
+ * reality, we will almost never get here, since addresses will usually be
+ * different. */
first_is_auth =
router_digest_is_trusted_dir(first->cache_info.identity_digest);
@@ -1839,7 +1841,9 @@
return _compare_routerinfo_by_id_digest(a, b);
}
-/** DOCDOC takes list of routerinfo */
+/** Given a list of routerinfo_t in <b>routers</b>, return a new digestmap_t
+ * whose keys are the identity digests of those routers that we're going to
+ * exclude for Sybil-like appearance. */
static digestmap_t *
get_possible_sybil_list(const smartlist_t *routers)
{
@@ -1868,7 +1872,11 @@
return omit_as_sybil;
}
-/** DOCDOC */
+/** Extract status information from <b>ri</b> and from other authority
+ * functions and store it in <b>rs</b>>. If <b>naming</b>, consider setting
+ * the named flag in <b>rs</b>. If not <b>exits_can_be_guards</b>, never mark
+ * an exit as a guard. If <b>listbadexits</b>, consider setting the badexit
+ * flag. */
static void
set_routerstatus_from_routerinfo(routerstatus_t *rs,
routerinfo_t *ri, time_t now,
@@ -1923,7 +1931,8 @@
rs->dir_port = ri->dir_port;
}
-/** DOCDOC */
+/** Return a new networkstatus_vote_t* containing our current opinion. (For v3
+ * authorities */
static networkstatus_vote_t *
generate_networkstatus_vote_obj(crypto_pk_env_t *private_key,
authority_cert_t *cert)
@@ -2062,7 +2071,9 @@
return v3_out;
}
-/* private DOCDOC */
+/** Return a new string containing teh string representation of the vote in
+ * <b>v3_ns</b>, signed with our v3 signing key <b>private_signing_key</b>.
+ * For v3 authorities. */
char *
format_networkstatus_vote(crypto_pk_env_t *private_signing_key,
networkstatus_vote_t *v3_ns)
@@ -2098,7 +2109,7 @@
*/
char *version_lines = NULL;
networkstatus_voter_info_t *voter;
- /* XXX check that everything gets freed */
+ /* XXX020 check that everything gets freed */
tor_assert(private_signing_key);
@@ -2793,7 +2804,9 @@
return found_any;
}
-/** DOCDOC */
+/** Return true iff we have any of the docments (extrainfo or routerdesc)
+ * specified by the fingerprints in <b>fps</b> and <b>spool_src</b>. Used to
+ * decide whether to send a 404. */
int
dirserv_have_any_serverdesc(smartlist_t *fps, int spool_src)
{
Modified: tor/trunk/src/or/dirvote.c
===================================================================
--- tor/trunk/src/or/dirvote.c 2007-08-22 15:07:29 UTC (rev 11254)
+++ tor/trunk/src/or/dirvote.c 2007-08-22 15:07:44 UTC (rev 11255)
@@ -732,7 +732,9 @@
return 0;
}
-/** DOCDOC */
+/** Given a v3 networkstatus consensus in <b>consensus</b>, check every
+ * as-yet-unchecked signature on <b>consensus. Return 0 if there are enough
+ * good signatures from recognized authorities on it, and -1 otherwise. */
int
networkstatus_check_consensus_signature(networkstatus_vote_t *consensus)
{
@@ -780,7 +782,16 @@
return -1;
}
-/** DOCDOC */
+/** Given a consensus vote <b>target</b> and a list of
+ * notworkstatus_voter_info_t in <b>src_voter_list</b> that correspond to the
+ * same consensus, check whether there are any new signatures in
+ * <b>src_voter_list</b> that should be added to <b>target. (A signature
+ * should be added if we have no signature for that voter in <b>target</b>
+ * yet, or if we have no verifiable signature and the new signature is
+ * verifiable.) Set *<b>new_signatures_out</b> to a newly allocated string
+ * holding the newly added signatures; set *<b>regenerate_out</b> to true if
+ * we replaced a signature and 0 otherwise. Return the number of signatures
+ * added or changed. */
static int
networkstatus_add_signatures_impl(networkstatus_vote_t *target,
smartlist_t *src_voter_list,
@@ -862,7 +873,8 @@
return r;
}
-/** DOCDOC */
+/** As networkstatus_add_consensus_signature_impl, but takes new signatures
+ * from the consensus in <b>src</b>. */
int
networkstatus_add_consensus_signatures(networkstatus_vote_t *target,
networkstatus_vote_t *src,
@@ -886,7 +898,8 @@
regenerate_out);
}
-/** DOCDOC */
+/** As networkstatus_add_consensus_signature_impl, but takes new signatures
+ * from the detached signatures document <b>sigs</b>. */
int
networkstatus_add_detached_signatures(networkstatus_vote_t *target,
ns_detached_signatures_t *sigs,
@@ -907,7 +920,8 @@
regenerate_out);
}
-/** DOCDOC */
+/** Return a newly allocated string holding the detached-signatures document
+ * corresponding to the signatures on <b>consensus</b>. */
char *
networkstatus_get_detached_signatures(networkstatus_vote_t *consensus)
{
@@ -965,7 +979,7 @@
return result;
}
-/** DOCDOC */
+/** Release all storage held in <b>s</b>. */
void
ns_detached_signatures_free(ns_detached_signatures_t *s)
{
@@ -1024,7 +1038,9 @@
* Vote scheduling
* ===== */
-/** DOCDOC */
+/** Set *<b>timing_out</b> to the intervals at which we would like to vote.
+ * Note that these aren't the intervals we'll use to vote; they're the ones
+ * that we'll vote to use. */
void
dirvote_get_preferred_voting_intervals(vote_timing_t *timing_out)
{
@@ -1038,7 +1054,10 @@
timing_out->dist_delay = options->V3AuthDistDelay;
}
-/** DOCDOC */
+/** Return the start of the next interval of size <b>interval</b> (in seconds)
+ * after <b>now</b>. Midnight always starts a fresh interval, and if the last
+ * interval of a day would be truncated to less than half its size, it is
+ * rolled into the previous interval. */
time_t
dirvote_get_start_of_next_interval(time_t now, int interval)
{
@@ -1069,20 +1088,28 @@
return next;
}
-/** DOCDOC */
+/** Scheduling information for a voting interval. */
static struct {
+ /** When do we generate and distribute our vote for this interval? */
time_t voting_starts;
+ /** When do we give up on getting more votes and generate a consensus? */
time_t voting_ends;
+ /** When do we publish the consensus? */
time_t interval_starts;
+ /** When do we discard old votes and pending detached signatures? */
time_t discard_old_votes;
+ /* True iff we have generated and distributed our vote. */
int have_voted;
+ /* True iff we have built a consensus and sent the signatures around. */
int have_built_consensus;
+ /* True iff we have published our consensus. */
int have_published_consensus;
} voting_schedule = {0,0,0,0,0,0,0};
-/** DOCDOC */
+/** Set voting_schedule to hold the timing for the next vote we should be
+ * doing. */
void
dirvote_recalculate_timing(time_t now)
{
@@ -1100,8 +1127,7 @@
vote_delay = consensus->vote_seconds;
dist_delay = consensus->dist_seconds;
} else {
- /* XXXX020 drop this back down to 30 minutes. */
- interval = 1200;
+ interval = 30*60;
vote_delay = dist_delay = 300;
}
@@ -1123,7 +1149,7 @@
((end-start) - vote_delay - dist_delay)/2 ;
}
-/** DOCDOC */
+/** Entry point: Take whatever voting actions are pending as of <b>now</b>. */
void
dirvote_act(time_t now)
{
@@ -1165,24 +1191,30 @@
}
}
-/** DOCDOC */
+/** A vote networkstatus_vote_t and its unparsed body: held around so we can
+ * use it to generate a consensus (at voting_ends) and so we can serve it to
+ * other authorities that might want it. */
typedef struct pending_vote_t {
cached_dir_t *vote_body;
networkstatus_vote_t *vote;
} pending_vote_t;
-/** DOCDOC */
+/** List of pending_vote_t for the current vote. */
static smartlist_t *pending_vote_list = NULL;
-/** DOCDOC */
+/** The body of the consensus that we're currently building. Once we
+ * have it built, it goes into dirserv.c */
static char *pending_consensus_body = NULL;
-/** DOCDOC */
+/** The detached signatures for the consensus that we're currently
+ * building. */
static char *pending_consensus_signatures = NULL;
-/** DOCDOC */
+/** The parsed in-progress consensus document. */
static networkstatus_vote_t *pending_consensus = NULL;
-/** DOCDOC */
+/** List of ns_detached_signatures_t: hold signatures that get posted to us
+ * before we have generated the consensus on our own. */
static smartlist_t *pending_consensus_signature_list = NULL;
-/** DOCDOC */
+/** Generate a networkstatus vote and post it to all the v3 authorities.
+ * (V3 Authority only) */
void
dirvote_perform_vote(void)
{
@@ -1208,7 +1240,7 @@
log_notice(LD_DIR, "Vote posted.");
}
-/** DOCDOC */
+/** Drop all currently pending votes, consensus, and detached signatures. */
void
dirvote_clear_pending_votes(void)
{
@@ -1251,7 +1283,11 @@
return keys;
}
-/** DOCDOC */
+/** Called when we have received a networkstatus vote in <b>vote_body</b>.
+ * Parse and validate it, and on success store it as a pending vote (which we
+ * then return). Return NULL on failure. Sets *<b>msg_out</b> and
+ * *<b>status_out</b> to an HTTP response and status code. (V3 authority
+ * only) */
pending_vote_t *
dirvote_add_vote(const char *vote_body, const char **msg_out, int *status_out)
{
@@ -1351,7 +1387,10 @@
return NULL;
}
-/** DOCDOC */
+/** Try to compute a v3 networkstatus consensus from the currently pending
+ * votes. Return 0 on success, -1 on failure. Store the consensus in
+ * pending_consensus: it won't be ready to be published until we have
+ * everybody else's signatures collected too. (V3 Authoritity only) */
int
dirvote_compute_consensus(void)
{
@@ -1448,7 +1487,9 @@
return -1;
}
-/** DOCDOC */
+/** Helper: we just got the <b>deteached_signatures_body</b> sent to us as
+ * signatures on the currently pending consensus. Add them to the consensus
+ * as appropriate. Return the number of signatures added. (?) */
static int
dirvote_add_signatures_to_pending_consensus(
const char *detached_signatures_body,
@@ -1541,10 +1582,14 @@
return r;
}
-/** DOCDOC */
+/** Helper: we just got the <b>deteached_signatures_body</b> sent to us as
+ * signatures on the currently pending consensus. Add them to the pending
+ * consensus (if we have one); otherwise queue them until we have a
+ * consensus. */
int
dirvote_add_signatures(const char *detached_signatures_body)
{
+ /*XXXX020 return value is senseless. */
if (pending_consensus) {
const char *msg=NULL;
log_notice(LD_DIR, "Got a signature. Adding it to the pending consensus.");
@@ -1560,7 +1605,8 @@
}
}
-/** DOCDOC */
+/** Replace the consensus that we're currently serving with the one that we've
+ * been building. (V3 Authority only) */
int
dirvote_publish_consensus(void)
{
@@ -1606,21 +1652,24 @@
* Access to pending items.
* ==== */
-/** DOCDOC */
+/** Return the body of the consensus that we're currently trying to build. */
const char *
dirvote_get_pending_consensus(void)
{
return pending_consensus_body;
}
-/** DOCDOC */
+/** Return the signatures that we know for the consensus that we're currently
+ * trying to build */
const char *
dirvote_get_pending_detached_signatures(void)
{
return pending_consensus_signatures;
}
-/** DOCDOC */
+/** Return the vote for the authority with the v3 authority identity key
+ * digest <b>id</b>. If <b>id</b> is NULL, return our own vote. May return
+ * NULL if we have no vote for the authority in question. */
const cached_dir_t *
dirvote_get_vote(const char *id)
{
More information about the tor-commits
mailing list