Module documentation (and an important caveat) for dirvote.c

This commit is contained in:
Nick Mathewson 2016-10-24 09:21:54 -04:00
parent d1bcba19a9
commit 5382b174c5

View File

@ -26,6 +26,39 @@
/**
* \file dirvote.c
* \brief Functions to compute directory consensus, and schedule voting.
*
* This module is the center of the consensus-voting based directory
* authority system. With this system, a set of authorities first
* publish vote based on their opinions of the network, and then compute
* a consensus from those votes. Each authority signs the consensus,
* and clients trust the consensus if enough known authorities have
* signed it.
*
* The code in this module is only invoked on directory authorities. It's
* responsible for:
*
* <ul>
* <li>Generating this authority's vote networkstatus, based on the
* authority's view of the network as represented in dirserv.c
* <li>Formatting the vote networkstatus objects.
* <li>Generating the microdescriptors that correspond to our own
* vote.
* <li>Sending votes to all the other authorities.
* <li>Trying to fetch missing votes from other authorities.
* <li>Computing the consensus from a set of votes, as well as
* a "detached signature" object for other authorities to fetch.
* <li>Collecting other authorities' signatures on the same consensus,
* until there are enough.
* <li>Publishing the consensus to the reset of the directory system.
* <li>Scheduling all of the above operations.
* </ul>
*
* The main entry points are in dirvote_act(), which handles scheduled
* actions; and dirvote_add_vote() and dirvote_add_signatures(), which
* handle uploaded and downloaded votes and signatures.
*
* (See dir-spec.txt from torspec.git for a complete specification of
* the directory protocol and voting algorithms.)
**/
/** A consensus that we have built and are appending signatures to. Once it's
@ -1273,7 +1306,17 @@ compute_nth_protocol_set(int n, int n_voters, const smartlist_t *votes)
* value in a newly allocated string.
*
* Note: this function DOES NOT check whether the votes are from
* recognized authorities. (dirvote_add_vote does that.) */
* recognized authorities. (dirvote_add_vote does that.)
*
* <strong>WATCH OUT</strong>: You need to think before you change the
* behavior of this function, or of the functions it calls! If some
* authorities compute the consensus with a different algorithm than
* others, they will not reach the same result, and they will not all
* sign the same thing! If you really need to change the algorithm
* here, you should allocate a new "consensus_method" for the new
* behavior, and make the new behavior conditional on a new-enough
* consensus_method.
**/
char *
networkstatus_compute_consensus(smartlist_t *votes,
int total_authorities,