r17947@catbus: nickm | 2008-02-06 11:57:53 -0500

 Fix a bunch of DOCDOC items; document the --quiet flag; refactor a couple of XXXX020 items.


svn:r13405

doc/tor.1.in

@@ -49,7 +49,13 @@ List all valid options.
 .LP
 .TP
 \fB--version\fP
-Display Tor version.
+Display Tor version and exit.
+.LP
+.TP
+\fB--quiet\fP
+Do not start Tor with a console log unless explicitly requested to do
+so.  (By default, Tor starts out logging messages at level "notice" or
+higher to the console, until it has parsed its configuration.)
 .LP
 .TP
 Other options can be specified either on the command-line (\fI--option

src/common/log.c

@@ -457,8 +457,9 @@ close_log(logfile_t *victim)
   }
 }
 
-/** Add a log handler to send all messages of severity <b>loglevel</b>
+/** Add a log handler named <b>name</b> to send all messages of severity
- * or higher to <b>stream</b>. DOCDOC.*/
+ * between <b>loglevelMin</b> and <b>loglevelMax</b> (inclusive) to
+ * <b>stream</b>. */
 static void
 add_stream_log_impl(int loglevelMin, int loglevelMax,
                     const char *name, FILE *stream)

src/common/tortls.c

@@ -1304,38 +1304,3 @@ tor_tls_used_v1_handshake(tor_tls_t *tls)
   return 1;
 }
 
-#if SSL3_RANDOM_SIZE != TOR_TLS_RANDOM_LEN
-#error "The TOR_TLS_RANDOM_LEN macro is defined incorrectly.  That's a bug."
-#endif
-
-/** DOCDOC */
-int
-tor_tls_get_random_values(tor_tls_t *tls, char *client_random_out,
-                          char *server_random_out)
-{
-  tor_assert(tls && tls->ssl);
-  if (!tls->ssl->s3)
-    return -1;
-  memcpy(client_random_out, tls->ssl->s3->client_random, SSL3_RANDOM_SIZE);
-  memcpy(server_random_out, tls->ssl->s3->server_random, SSL3_RANDOM_SIZE);
-  return 0;
-}
-
-/** DOCDOC */
-int
-tor_tls_hmac_with_master_secret(tor_tls_t *tls, char *hmac_out,
-                                const char *data, size_t data_len)
-{
-  SSL_SESSION *s;
-  tor_assert(tls && tls->ssl);
-  if (!(s = SSL_get_session(tls->ssl)))
-    return -1;
-  if (s->master_key_length < 0)
-    return -1;
-  crypto_hmac_sha1(hmac_out,
-                   (const char*)s->master_key,
-                   (size_t)s->master_key_length,
-                   data, data_len);
-  return 0;
-}
-

src/common/tortls.h

@@ -43,9 +43,6 @@ typedef struct tor_tls_t tor_tls_t;
   case TOR_TLS_ERROR_NO_ROUTE:                  \
   case TOR_TLS_ERROR_TIMEOUT
 
-/**DOCDOC*/
-#define TOR_TLS_RANDOM_LEN 32
-
 #define TOR_TLS_IS_ERROR(rv) ((rv) < TOR_TLS_CLOSE)
 const char *tor_tls_err_to_string(int err);
 
@@ -79,10 +76,6 @@ void tor_tls_get_n_raw_bytes(tor_tls_t *tls,
                              size_t *n_read, size_t *n_written);
 
 int tor_tls_used_v1_handshake(tor_tls_t *tls);
-int tor_tls_get_random_values(tor_tls_t *tls, char *client_random_out,
-                              char *server_random_out);
-int tor_tls_hmac_with_master_secret(tor_tls_t *tls, char *hmac_out,
-                                    const char *data, size_t data_len);
 
 /* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
  */

src/common/util.c

@@ -1298,7 +1298,10 @@ parse_http_time(const char *date, struct tm *tm)
   return 0;
 }
 
-/** DOCDOC */
+/** Given an <b>interval</b> in seconds, try to write it to the
+ * <b>out_len</b>-byte buffer in <b>out</b> in a human-readable form.
+ * Return 0 on success, -1 on failure.
+ */
 int
 format_time_interval(char *out, size_t out_len, long interval)
 {
@@ -1932,13 +1935,19 @@ read_file_to_str(const char *filename, int flags, struct stat *stat_out)
 
 #define TOR_ISODIGIT(c) ('0' <= (c) && (c) <= '7')
 
-/* DOCDOC */
+/* Given a c-style double-quoted escaped string in <b>s</b>, extract and
+ * decode its contents into a newly allocated string.  On success, assign this
+ * string to *<b>result</b>, assign its length to <b>size_out</b> (if
+ * provided), and return a pointer to the position in <b>s</b> immediately
+ * after the string.  On failure, return NULL.
+ */
 static const char *
 unescape_string(const char *s, char **result, size_t *size_out)
 {
   const char *cp;
   char *out;
-  tor_assert(s[0] == '\"');
+  if (s[0] != '\"')
+    return NULL;
   cp = s+1;
   while (1) {
     switch (*cp) {

src/or/buffers.c

@@ -580,6 +580,7 @@ read_to_chunk(buf_t *buf, chunk_t *chunk, int fd, size_t at_most,
   }
 }
 
+/** DOCDOC */
 static INLINE int
 read_to_chunk_tls(buf_t *buf, chunk_t *chunk, tor_tls_t *tls,
                   size_t at_most)
@@ -722,6 +723,7 @@ flush_chunk(int s, buf_t *buf, chunk_t *chunk, size_t sz,
   }
 }
 
+/** DOCDOC */
 static INLINE int
 flush_chunk_tls(tor_tls_t *tls, buf_t *buf, chunk_t *chunk,
                 size_t sz, size_t *buf_flushlen)
@@ -1518,7 +1520,8 @@ peek_buf_has_control0_command(buf_t *buf)
   return 0;
 }
 
-/** DOCDOC */
+/** Return the index within <b>buf</b> at which <b>ch</b> first appears,
+ * or -1 if <b>ch</b> does not appear on buf. */
 static int
 buf_find_offset_of_char(buf_t *buf, char ch)
 {

src/or/connection.c

@@ -1650,7 +1650,10 @@ connection_bucket_init(void)
   }
 }
 
-/** DOCDOC */
+/** Refill a single <b>bucket</b> called <b>name</b> with bandwith rate
+ * <b>rate</b> and bandwidth burst <b>burst</b>, assuming that
+ * <b>seconds_elapsed</b> seconds have passed since the last call.
+ **/
 static void
 connection_bucket_refill_helper(int *bucket, int rate, int burst,
                                 int seconds_elapsed, const char *name)

src/or/control.c

@@ -364,42 +364,55 @@ read_escaped_data(const char *data, size_t len, char **out)
   return outp - *out;
 }
 
-/** DOCDOC */
+/** If the first <b>in_len_max</b> characters in <b>start<b> contain a
-static const char *
+ * double-quoted string with escaped characters, return the length of that
-extract_escaped_string(const char *start, size_t in_len_max,
+ * string (as encoded, including quotes).  Otherwise return -1. */
-                       char **out, size_t *out_len)
+static INLINE int
+get_escaped_string_length(const char *start, size_t in_len_max,
+                          int *chars_out)
 {
   const char *cp, *end;
-  size_t len=0;
+  int chars = 0;
 
   if (*start != '\"')
-    return NULL;
+    return -1;
 
   cp = start+1;
   end = start+in_len_max;
 
   /* Calculate length. */
   while (1) {
-    if (cp >= end)
+    if (cp >= end) {
-      return NULL;
+      return -1; /* Too long. */
-    else if (*cp == '\\') {
+    } else if (*cp == '\\') {
       if (++cp == end)
-        return NULL; /* Can't escape EOS. */
+        return -1; /* Can't escape EOS. */
       ++cp;
-      ++len;
+      ++chars;
     } else if (*cp == '\"') {
       break;
     } else {
       ++cp;
-      ++len;
+      ++chars;
     }
   }
-  end = cp;
+  if (chars_out)
+    *chars_out = chars;
+  return cp - start+1;
+}
 
-  *out_len = end-start+1;
+/** As decode_escaped_string, but does not decode the string: copies the
+ * entire thing, including quotation marks. */
+static const char *
+extract_escaped_string(const char *start, size_t in_len_max,
+                       char **out, size_t *out_len)
+{
+  int length = get_escaped_string_length(start, in_len_max, NULL);
+  if (length<0)
+    return NULL;
+  *out_len = length;
   *out = tor_strndup(start, *out_len);
-
+  return start+length;
-  return end+1;
 }
 
 /** Given a pointer to a string starting at <b>start</b> containing
@@ -410,40 +423,22 @@ extract_escaped_string(const char *start, size_t in_len_max,
  * store its length in <b>out_len</b>.  On success, return a pointer to the
  * character immediately following the escaped string.  On failure, return
  * NULL. */
-/* XXXX020 fold into extract_escaped_string */
 static const char *
-get_escaped_string(const char *start, size_t in_len_max,
+decode_escaped_string(const char *start, size_t in_len_max,
                    char **out, size_t *out_len)
 {
   const char *cp, *end;
   char *outp;
-  size_t len=0;
+  int len, n_chars = 0;
 
-  if (*start != '\"')
+  len = get_escaped_string_length(start, in_len_max, &n_chars);
+  if (len<0)
     return NULL;
 
-  cp = start+1;
+  end = start+len-1; /* Index of last quote. */
-  end = start+in_len_max;
+  tor_assert(*end == '\"');
-
-  /* Calculate length. */
-  while (1) {
-    if (cp >= end)
-      return NULL;
-    else if (*cp == '\\') {
-      if (++cp == end)
-        return NULL; /* Can't escape EOS. */
-      ++cp;
-      ++len;
-    } else if (*cp == '\"') {
-      break;
-    } else {
-      ++cp;
-      ++len;
-    }
-  }
-  end = cp;
   outp = *out = tor_malloc(len+1);
-  *out_len = len;
+  *out_len = n_chars;
 
   cp = start+1;
   while (cp < end) {
@@ -1030,7 +1025,7 @@ handle_control_authenticate(control_connection_t *conn, uint32_t len,
     password = tor_strdup("");
     password_len = 0;
   } else {
-    if (!get_escaped_string(body, len, &password, &password_len)) {
+    if (!decode_escaped_string(body, len, &password, &password_len)) {
       connection_write_str_to_buf("551 Invalid quoted string.  You need "
             "to put the password in double quotes.\r\n", conn);
       connection_mark_for_close(TO_CONN(conn));

src/or/cpuworker.c

@@ -431,10 +431,13 @@ cull_wedged_cpuworkers(void)
   });
 }
 
-/** If cpuworker is defined, assert that he's idle, and use him. Else,
+/** Try to tell a cpuworker to perform the public key operations necessary to
- * look for an idle cpuworker and use him. If none idle, queue task onto
+ * respond to <b>onionskin</b> for the circuit <b>circ</b>.
- * the pending onion list and return.
+ *
- * DOCDOC this function is now less general
+ * If <b>cpuworker</b> is defined, assert that he's idle, and use him. Else,
+ * look for an idle cpuworker and use him. If none idle, queue task onto the
+ * pending onion list and return.  Return 0 if we successfully assign the
+ * task, or -1 on failure.
  */
 int
 assign_onionskin_to_cpuworker(connection_t *cpuworker,

src/or/dirserv.c

@@ -2283,16 +2283,6 @@ dirserv_generate_networkstatus_vote_obj(crypto_pk_env_t *private_key,
 static cached_dir_t *
 generate_v2_networkstatus_opinion(void)
 {
-/** Amount of space to allocate for each entry. (r line and s line.) */
-#define RS_ENTRY_LEN                                                    \
-  ( /* first line */                                                    \
-   MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \
-   5*2 /* ports */ + 10 /* punctuation */ +                             \
-   /* second line */                                                    \
-   (MAX_FLAG_LINE_LEN) +                                                \
-   /* third line */                                                     \
-   (MAX_V_LINE_LEN))
-
   cached_dir_t *r = NULL;
   size_t len, identity_pkey_len;
   char *status = NULL, *client_versions = NULL, *server_versions = NULL,

src/or/dirvote.c

@@ -36,17 +36,6 @@ char *
 format_networkstatus_vote(crypto_pk_env_t *private_signing_key,
                           networkstatus_t *v3_ns)
 {
-/** Amount of space to allocate for each entry: r, s, and v lines. */
-#define RS_ENTRY_LEN                                                    \
-  ( /* first line */                                                    \
-   MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \
-   5*2 /* ports */ + 10 /* punctuation */ +                             \
-   /* second line */                                                    \
-   MAX_FLAG_LINE_LEN +                                                  \
-   /* v line. */                                                        \
-   MAX_V_LINE_LEN                                                       \
-   )
-
   size_t len;
   char *status = NULL;
   const char *client_versions = NULL, *server_versions = NULL;
@@ -367,22 +356,28 @@ hash_list_members(char *digest_out, smartlist_t *lst)
   crypto_free_digest_env(d);
 }
 
-/**DOCDOC*/
+/** Sorting helper: compare two strings based on their values as base-ten
+ * positive integers. (Non-integers are treated as prior to all integers, and
+ * compared lexically.) */
 static int
 _cmp_int_strings(const void **_a, const void **_b)
 {
   const char *a = *_a, *b = *_b;
   int ai = (int)tor_parse_long(a, 10, 1, INT_MAX, NULL, NULL);
   int bi = (int)tor_parse_long(b, 10, 1, INT_MAX, NULL, NULL);
-  if (ai<bi)
+  if (ai<bi) {
     return -1;
-  else if (ai==bi)
+  } else if (ai==bi) {
+    if (ai == 0) /* Parsing failed. */
+      return strcmp(a, b);
     return 0;
-  else
+  } else {
     return 1;
+  }
 }
 
-/**DOCDOC*/
+/** Given a list of networkstatus_t votes, determine and return the number of
+ * the highest consensus method that is supported by 2/3 of the voters. */
 static int
 compute_consensus_method(smartlist_t *votes)
 {
@@ -417,7 +412,7 @@ compute_consensus_method(smartlist_t *votes)
   return result;
 }
 
-/**DOCDOC*/
+/** Return true iff <b>method</b> is a consensus method that we support. */
 static int
 consensus_method_is_supported(int method)
 {

src/or/main.c

@@ -1785,7 +1785,7 @@ tor_init(int argc, char *argv[])
   /* We search for the "quiet" option first, since it decides whether we
    * will log anything at all to the command line. */
   for (i=1;i<argc;++i) {
-    if (!strcmp(argv[i], "--quiet")) /*DOCDOC in mangpage.*/
+    if (!strcmp(argv[i], "--quiet"))
       quiet = 1;
   }
   if (!quiet) {

src/or/networkstatus.c

@@ -1206,6 +1206,7 @@ networkstatus_get_live_consensus(time_t now)
 /* 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 */
 networkstatus_t *
 networkstatus_get_reasonably_live_consensus(time_t now)
 {
@@ -1781,8 +1782,7 @@ signed_descs_update_status_from_consensus_networkstatus(smartlist_t *descs)
 char *
 networkstatus_getinfo_helper_single(routerstatus_t *rs)
 {
-  char buf[256];
+  char buf[RS_ENTRY_LEN+1];
-  /* XXX020 that 256 above sounds a lot like RS_ENTRY_LEN in dirvote.c */
   routerstatus_format_entry(buf, sizeof(buf), rs, NULL, 0);
   return tor_strdup(buf);
 }

src/or/or.h

@@ -3058,6 +3058,16 @@ download_status_is_ready(download_status_t *dls, time_t now,
 /** Length of "r Authority BadDirectory BadExit Exit Fast Guard HSDir Named
  * Running Stable Unnamed V2Dir Valid\n". */
 #define MAX_FLAG_LINE_LEN 96
+/** Amount of space to allocate for each entry: r, s, and v lines. */
+#define RS_ENTRY_LEN                                                    \
+  ( /* first line */                                                    \
+   MAX_NICKNAME_LEN+BASE64_DIGEST_LEN*2+ISO_TIME_LEN+INET_NTOA_BUF_LEN+ \
+   5*2 /* ports */ + 10 /* punctuation */ +                             \
+   /* second line */                                                    \
+   MAX_FLAG_LINE_LEN +                                                  \
+   /* v line. */                                                        \
+   MAX_V_LINE_LEN                                                       \
+   )
 #define UNNAMED_ROUTER_NICKNAME "Unnamed"
 
 int connection_dirserv_flushed_some(dir_connection_t *conn);

src/or/policies.c

@@ -744,7 +744,7 @@ policies_parse_exit_policy(config_line_t *cfg, smartlist_t **dest,
   return 0;
 }
 
-/** DOCDOC */
+/** Replace the exit policy of <b>r</b> with reject *:*. */
 void
 policies_set_router_exitpolicy_to_reject_all(routerinfo_t *r)
 {

src/or/rendservice.c

@@ -48,6 +48,7 @@ typedef struct rend_service_t {
   char *intro_prefer_nodes; /**< comma-separated list of nicknames */
   char *intro_exclude_nodes; /**< comma-separated list of nicknames */
   /* Other fields */
+  /* DOCDOC All of these fields */
   crypto_pk_env_t *private_key;
   char service_id[REND_SERVICE_ID_LEN_BASE32+1];
   char pk_digest[DIGEST_LEN];
@@ -56,7 +57,6 @@ typedef struct rend_service_t {
   time_t intro_period_started;
   int n_intro_circuits_launched; /**< count of intro circuits we have
                                   * established in this period. */
-  /* DOCDOC undocumented versions */
   rend_service_descriptor_t *desc;
   time_t desc_is_dirty;
   time_t next_upload_time;

src/or/routerlist.c

@@ -55,7 +55,8 @@ DECLARE_TYPED_DIGESTMAP_FNS(eimap_, digest_ei_map_t, extrainfo_t)
  * server. */
 static smartlist_t *trusted_dir_servers = NULL;
 
-/** DOCDOC */
+/** List of for a given authority, and download status for latest certificate.
+ */
 typedef struct cert_list_t {
   download_status_t dl_status;
   smartlist_t *certs;
@@ -95,7 +96,8 @@ get_n_authorities(authority_type_t type)
 
 #define get_n_v2_authorities() get_n_authorities(V2_AUTHORITY)
 
-/** DOCDOC */
+/** Helper: Return the cert_list_t for an authority whose authority ID is
+ * <b>id_digest</b>, allocating a new list if necessary. */
 static cert_list_t *
 get_cert_list(const char *id_digest)
 {
@@ -328,10 +330,11 @@ authority_cert_get_by_digests(const char *id_digest,
   return NULL;
 }
 
-/** DOCDOC */
+/** Add every known authority_cert_t to <b>certs_out</b>. */
 void
 authority_cert_get_all(smartlist_t *certs_out)
 {
+  tor_assert(certs_out);
   if (!trusted_dir_certs)
     return;
 
@@ -341,7 +344,9 @@ authority_cert_get_all(smartlist_t *certs_out)
   } DIGESTMAP_FOREACH_END;
 }
 
-/** DOCDOC */
+/** Called when an attempt to download a certificate with the authority with
+ * ID <b>id_digest</b> fails with HTTP response code <b>status</b>: remember
+ * the failure, so we don't try again immediately. */
 void
 authority_cert_dl_failed(const char *id_digest, int status)
 {

src/tools/tor-gencert.c

@@ -36,6 +36,7 @@
 #define SIGNING_KEY_BITS 1024
 #define DEFAULT_LIFETIME 12
 
+/* These globals are set via command line options. */
 char *identity_key_file = NULL;
 char *signing_key_file = NULL;
 char *certificate_file = NULL;
@@ -48,7 +49,7 @@ char *address = NULL;
 EVP_PKEY *identity_key = NULL;
 EVP_PKEY *signing_key = NULL;
 
-/* DOCDOC */
+/** Write a usage message for tor-gencert to stderr. */
 static void
 show_help(void)
 {
@@ -82,7 +83,9 @@ crypto_log_errors(int severity, const char *doing)
   }
 }
 
-/** DOCDOC */
+/** Read the command line options from <b>argc</b> and <b>argv</b>,
+ * setting global option vars as needed.
+ */
 static int
 parse_commandline(int argc, char **argv)
 {
@@ -170,7 +173,10 @@ parse_commandline(int argc, char **argv)
   return 0;
 }
 
-/** DOCDOC */
+/** Try to read the identity key from <b>identity_key_file</b>.  If no such
+ * file exists and create_identity_key is set, make a new identity key and
+ * store it.  Return 0 on success, nonzero on failure.
+ */
 static int
 load_identity_key(void)
 {
@@ -240,7 +246,8 @@ load_identity_key(void)
   return 0;
 }
 
-/** DOCDOC */
+/** Load a saved signing key from disk.  Return 0 on success, nonzero on
+ * failure. */
 static int
 load_signing_key(void)
 {
@@ -258,7 +265,8 @@ load_signing_key(void)
   return 0;
 }
 
-/** DOCDOC */
+/** Generate a new signing key and write it to disk.  Return 0 on success,
+ * nonzero on failure. */
 static int
 generate_signing_key(void)
 {
@@ -295,6 +303,8 @@ generate_signing_key(void)
   return 0;
 }
 
+/** Encode <b>key</b> in the format used in directory documents; return
+ * a newly allocated string holding the result or NULL on failure. */
 static char *
 key_to_string(EVP_PKEY *key)
 {
@@ -322,6 +332,7 @@ key_to_string(EVP_PKEY *key)
   return result;
 }
 
+/** Set <b>out</b> to the hex-encoded fingerprint of <b>pkey</b>. */
 static int
 get_fingerprint(EVP_PKEY *pkey, char *out)
 {
@@ -334,6 +345,8 @@ get_fingerprint(EVP_PKEY *pkey, char *out)
   return r;
 }
 
+/** Generate a new certificate for our loaded or generated keys, and write it
+ * to disk.  Return 0 on success, nonzero on failure. */
 static int
 generate_certificate(void)
 {