More documentation

svn:r1785

3 files changed, 63 insertions, 8 deletions

diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index cd7ab0e00d..c7590036fc 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -4,6 +4,10 @@
 
 #include "or.h"
 
+/*****
+ * dirserv.c: Directory server core implementation.
+ *****/
+
 /* How old do we allow a router to get before removing it? (seconds) */
 #define ROUTER_MAX_AGE (60*60*24)
 
@@ -12,6 +16,7 @@
 
 extern or_options_t options; /* command-line and config-file options */
 
+/* Do we need to regenerate the directory when someone asks for it? */
 static int the_directory_is_dirty = 1;
 
 static int list_running_servers(char **nicknames_out);
@@ -24,9 +29,14 @@ typedef struct fingerprint_entry_t {
   char *fingerprint;
 } fingerprint_entry_t;
 
+/* List of nickname->identity fingerprint mappings for all the routers
+ * that we recognize. Used to prevent Sybil attacks. */
 static fingerprint_entry_t fingerprint_list[MAX_ROUTERS_IN_DIR];
 static int n_fingerprints = 0;
 
+/* Add the fingerprint 'fp' for the nickname 'nickname' to the global
+ * list of recognized identity key fingerprints.
+ */
 void /* Should be static; exposed for testing */
 add_fingerprint_to_dir(const char *nickname, const char *fp)
 {
@@ -43,6 +53,8 @@ add_fingerprint_to_dir(const char *nickname, const char *fp)
   ++n_fingerprints;
 }
 
+/* Add the nickname and fingerprint for this OR to the recognized list.
+ */
 int
 dirserv_add_own_fingerprint(const char *nickname, crypto_pk_env_t *pk)
 {
@@ -55,7 +67,12 @@ dirserv_add_own_fingerprint(const char *nickname, crypto_pk_env_t *pk)
   return 0;
 }
 
-/* return 0 on success, -1 on failure */
+/* Parse the nickname->fingerprint mappings stored in the file named
+ * 'fname'.  The file format is line-based, with each non-blank
+ * holding one nickname, some space, and a fingerprint for that
+ * nickname.  On success, replace the current fingerprint list with
+ * the contents of 'fname' and return 0.  On failure, leave the
+ * current fingerprint list untouched, and return -1. */
 int
 dirserv_parse_fingerprint_file(const char *fname)
 {
@@ -112,8 +129,10 @@ dirserv_parse_fingerprint_file(const char *fname)
   return -1;
 }
 
-/* return 1 if router's identity and nickname match,
- * -1 if they don't match, 0 if the nickname is not known. */
+/* Check whether 'router' has a nickname/identity key combination that
+ * we recognize from the fingerprint list.  Return 1 if router's
+ * identity and nickname match, -1 if we recognize the nickname but
+ * the identity key is wrong, and 0 if the nickname is not known. */
 int
 dirserv_router_fingerprint_is_known(const routerinfo_t *router)
 {
@@ -147,6 +166,7 @@ dirserv_router_fingerprint_is_known(const routerinfo_t *router)
   }
 }
 
+/* Clear the current fingerprint list. */
 void
 dirserv_free_fingerprint_list()
 {
@@ -161,6 +181,9 @@ dirserv_free_fingerprint_list()
 /*
  *    Descriptor list
  */
+
+/* A directory server's view of a server descriptor.  Contains both
+ * parsed and unparsed versions. */
 typedef struct descriptor_entry_t {
   char *nickname;
   time_t published;
@@ -169,9 +192,11 @@ typedef struct descriptor_entry_t {
   routerinfo_t *router;
 } descriptor_entry_t;
 
+/* List of all server descriptors that this dirserv is holding. */
 static descriptor_entry_t *descriptor_list[MAX_ROUTERS_IN_DIR];
 static int n_descriptors = 0;
 
+/* Release the storage held by 'desc' */
 static void free_descriptor_entry(descriptor_entry_t *desc)
 {
   tor_free(desc->descriptor);
@@ -180,6 +205,8 @@ static void free_descriptor_entry(descriptor_entry_t *desc)
   free(desc);
 }
 
+/* Release all storage that the dirserv is holding for server
+ * descriptors. */
 void
 dirserv_free_descriptors()
 {
@@ -190,12 +217,13 @@ dirserv_free_descriptors()
   n_descriptors = 0;
 }
 
-/* Return 1 if descriptor is well-formed and accepted;
- * 0 if well-formed and server or descriptor is unapproved;
- * -1 if not well-formed or other error.
+/* Parse the server descriptor at *desc and maybe insert it into the
+ * list of service descriptors, and (if the descriptor is well-formed)
+ * advance *desc immediately past the descriptor's end.
  *
- * Update *desc to point after the descriptor if the
- * descriptor is well-formed.
+ * Return 1 if descriptor is well-formed and accepted;
+ * 0 if well-formed and server is unapproved;
+ * -1 if not well-formed or other error.
  */
 int
 dirserv_add_descriptor(const char **desc)
@@ -307,6 +335,10 @@ dirserv_add_descriptor(const char **desc)
   return 1;
 }
 
+/* Remove all descriptors whose nicknames or fingerprints we don't
+ * recognize.  (Descriptors that used to be good can become
+ * unrecognized when we reload the fingerprint list.)
+ */
 static void
 directory_remove_unrecognized(void)
 {
@@ -321,12 +353,19 @@ directory_remove_unrecognized(void)
   }
 }
 
+/* Mark the directory as 'dirty' -- when we're next asked for a
+ * directory, we will rebuild it instead of reusing the most recently
+ * generated one.
+ */
 void
 directory_set_dirty()
 {
   the_directory_is_dirty = 1;
 }
 
+/* Load all descriptors from an earlier directory stored in the string
+ * 'dir'.
+ */
 int
 dirserv_init_from_directory_string(const char *dir)
 {
@@ -343,6 +382,10 @@ dirserv_init_from_directory_string(const char *dir)
   return 0;
 }
 
+/* Set *nicknames_out to a comma-separated list of all the ORs that we
+ * believe are currently running (because we have open connections to
+ * them).  Return 0 on success; -1 on error.
+ */
 static int
 list_running_servers(char **nicknames_out)
 {
diff --git a/src/or/router.c b/src/or/router.c
index d404e6c7c2..dbbe73196f 100644
--- a/src/or/router.c
+++ b/src/or/router.c
@@ -4,6 +4,11 @@
 
 #include "or.h"
 
+/*****
+ * router.c: OR functionality, including key maintenance, generating
+ * and uploading server descriptors, retrying OR connections.
+ *****/
+
 extern or_options_t options; /* command-line and config-file options */
 
 /* exposed for test.c */ void get_platform_str(char *platform, int len);
diff --git a/src/or/routerlist.c b/src/or/routerlist.c
index 858286f312..d8cf1a0c78 100644
--- a/src/or/routerlist.c
+++ b/src/or/routerlist.c
@@ -9,6 +9,13 @@
 
 #include "or.h"
 
+/*****
+ * routerlist.c: Code to parse descriptors and directories, and to
+ * maintain and access the global list of routerinfos for known
+ * servers.
+ *****/
+
+
 /****************************************************************************/
 
 extern or_options_t options; /* command-line and config-file options */