[tor-commits] [tor/master] shared_random.[ch]: repair doxygen comments

nickm at torproject.org nickm at torproject.org
Wed Oct 16 16:05:23 UTC 2019


commit 18ea8855f2c8246f76afa8cb6f30655d8872e338
Author: Nick Mathewson <nickm at torproject.org>
Date:   Wed Oct 16 12:04:53 2019 -0400

    shared_random.[ch]: repair doxygen comments
---
 src/feature/dirauth/shared_random.c | 77 +++++++++++++++++++------------------
 src/feature/dirauth/shared_random.h | 59 ++++++++++++++--------------
 2 files changed, 69 insertions(+), 67 deletions(-)

diff --git a/src/feature/dirauth/shared_random.c b/src/feature/dirauth/shared_random.c
index a45f0a29c..2b9dc0c38 100644
--- a/src/feature/dirauth/shared_random.c
+++ b/src/feature/dirauth/shared_random.c
@@ -107,19 +107,19 @@
 #include "feature/nodelist/authority_cert_st.h"
 #include "feature/nodelist/networkstatus_st.h"
 
-/* String prefix of shared random values in votes/consensuses. */
+/** String prefix of shared random values in votes/consensuses. */
 static const char previous_srv_str[] = "shared-rand-previous-value";
 static const char current_srv_str[] = "shared-rand-current-value";
 static const char commit_ns_str[] = "shared-rand-commit";
 static const char sr_flag_ns_str[] = "shared-rand-participate";
 
-/* The value of the consensus param AuthDirNumSRVAgreements found in the
+/** The value of the consensus param AuthDirNumSRVAgreements found in the
  * vote. This is set once the consensus creation subsystem requests the
  * SRV(s) that should be put in the consensus. We use this value to decide
  * if we keep or not an SRV. */
 static int32_t num_srv_agreements_from_vote;
 
-/* Return a heap allocated copy of the SRV <b>orig</b>. */
+/** Return a heap allocated copy of the SRV <b>orig</b>. */
 sr_srv_t *
 sr_srv_dup(const sr_srv_t *orig)
 {
@@ -135,7 +135,7 @@ sr_srv_dup(const sr_srv_t *orig)
   return duplicate;
 }
 
-/* Allocate a new commit object and initializing it with <b>rsa_identity</b>
+/** Allocate a new commit object and initializing it with <b>rsa_identity</b>
  * that MUST be provided. The digest algorithm is set to the default one
  * that is supported. The rest is uninitialized. This never returns NULL. */
 static sr_commit_t *
@@ -153,7 +153,7 @@ commit_new(const char *rsa_identity)
   return commit;
 }
 
-/* Issue a log message describing <b>commit</b>. */
+/** Issue a log message describing <b>commit</b>. */
 static void
 commit_log(const sr_commit_t *commit)
 {
@@ -166,7 +166,7 @@ commit_log(const sr_commit_t *commit)
             commit->reveal_ts, safe_str(commit->encoded_reveal));
 }
 
-/* Make sure that the commitment and reveal information in <b>commit</b>
+/** Make sure that the commitment and reveal information in <b>commit</b>
  * match. If they match return 0, return -1 otherwise. This function MUST be
  * used everytime we receive a new reveal value. Furthermore, the commit
  * object MUST have a reveal value and the hash of the reveal value. */
@@ -220,7 +220,7 @@ verify_commit_and_reveal(const sr_commit_t *commit)
   return -1;
 }
 
-/* Return true iff the commit contains an encoded reveal value. */
+/** Return true iff the commit contains an encoded reveal value. */
 STATIC int
 commit_has_reveal_value(const sr_commit_t *commit)
 {
@@ -228,7 +228,7 @@ commit_has_reveal_value(const sr_commit_t *commit)
                           sizeof(commit->encoded_reveal));
 }
 
-/* Parse the encoded commit. The format is:
+/** Parse the encoded commit. The format is:
  *    base64-encode( TIMESTAMP || H(REVEAL) )
  *
  * If successfully decoded and parsed, commit is updated and 0 is returned.
@@ -283,7 +283,7 @@ commit_decode(const char *encoded, sr_commit_t *commit)
   return -1;
 }
 
-/* Parse the b64 blob at <b>encoded</b> containing reveal information and
+/** Parse the b64 blob at <b>encoded</b> containing reveal information and
  * store the information in-place in <b>commit</b>. Return 0 on success else
  * a negative value. */
 STATIC int
@@ -333,7 +333,7 @@ reveal_decode(const char *encoded, sr_commit_t *commit)
   return -1;
 }
 
-/* Encode a reveal element using a given commit object to dst which is a
+/** Encode a reveal element using a given commit object to dst which is a
  * buffer large enough to put the base64-encoded reveal construction. The
  * format is as follow:
  *     REVEAL = base64-encode( TIMESTAMP || H(RN) )
@@ -362,7 +362,7 @@ reveal_encode(const sr_commit_t *commit, char *dst, size_t len)
   return ret;
 }
 
-/* Encode the given commit object to dst which is a buffer large enough to
+/** Encode the given commit object to dst which is a buffer large enough to
  * put the base64-encoded commit. The format is as follow:
  *     COMMIT = base64-encode( TIMESTAMP || H(H(RN)) )
  * Return base64 encoded length on success else a negative value.
@@ -388,14 +388,14 @@ commit_encode(const sr_commit_t *commit, char *dst, size_t len)
   return base64_encode(dst, len, buf, sizeof(buf), 0);
 }
 
-/* Cleanup both our global state and disk state. */
+/** Cleanup both our global state and disk state. */
 static void
 sr_cleanup(void)
 {
   sr_state_free_all();
 }
 
-/* Using <b>commit</b>, return a newly allocated string containing the commit
+/** Using <b>commit</b>, return a newly allocated string containing the commit
  * information that should be used during SRV calculation. It's the caller
  * responsibility to free the memory. Return NULL if this is not a commit to be
  * used for SRV calculation. */
@@ -414,7 +414,7 @@ get_srv_element_from_commit(const sr_commit_t *commit)
   return element;
 }
 
-/* Return a srv object that is built with the construction:
+/** Return a srv object that is built with the construction:
  *    SRV = SHA3-256("shared-random" | INT_8(reveal_num) |
  *                   INT_4(version) | HASHED_REVEALS | previous_SRV)
  * This function cannot fail. */
@@ -456,7 +456,7 @@ generate_srv(const char *hashed_reveals, uint64_t reveal_num,
   return srv;
 }
 
-/* Compare reveal values and return the result. This should exclusively be
+/** Compare reveal values and return the result. This should exclusively be
  * used by smartlist_sort(). */
 static int
 compare_reveal_(const void **_a, const void **_b)
@@ -466,7 +466,7 @@ compare_reveal_(const void **_a, const void **_b)
                      sizeof(a->hashed_reveal));
 }
 
-/* Given <b>commit</b> give the line that we should place in our votes.
+/** Given <b>commit</b> give the line that we should place in our votes.
  * It's the responsibility of the caller to free the string. */
 static char *
 get_vote_line_from_commit(const sr_commit_t *commit, sr_phase_t phase)
@@ -506,7 +506,7 @@ get_vote_line_from_commit(const sr_commit_t *commit, sr_phase_t phase)
   return vote_line;
 }
 
-/* Return a heap allocated string that contains the given <b>srv</b> string
+/** Return a heap allocated string that contains the given <b>srv</b> string
  * representation formatted for a networkstatus document using the
  * <b>key</b> as the start of the line. This doesn't return NULL. */
 static char *
@@ -524,7 +524,7 @@ srv_to_ns_string(const sr_srv_t *srv, const char *key)
   return srv_str;
 }
 
-/* Given the previous SRV and the current SRV, return a heap allocated
+/** Given the previous SRV and the current SRV, return a heap allocated
  * string with their data that could be put in a vote or a consensus. Caller
  * must free the returned string.  Return NULL if no SRVs were provided. */
 static char *
@@ -557,7 +557,7 @@ get_ns_str_from_sr_values(const sr_srv_t *prev_srv, const sr_srv_t *cur_srv)
   return srv_str;
 }
 
-/* Return 1 iff the two commits have the same commitment values. This
+/** Return 1 iff the two commits have the same commitment values. This
  * function does not care about reveal values. */
 STATIC int
 commitments_are_the_same(const sr_commit_t *commit_one,
@@ -572,7 +572,7 @@ commitments_are_the_same(const sr_commit_t *commit_one,
   return 1;
 }
 
-/* We just received a commit from the vote of authority with
+/** We just received a commit from the vote of authority with
  * <b>identity_digest</b>. Return 1 if this commit is authorititative that
  * is, it belongs to the authority that voted it. Else return 0 if not. */
 STATIC int
@@ -586,7 +586,7 @@ commit_is_authoritative(const sr_commit_t *commit,
                     sizeof(commit->rsa_identity));
 }
 
-/* Decide if the newly received <b>commit</b> should be kept depending on
+/** Decide if the newly received <b>commit</b> should be kept depending on
  * the current phase and state of the protocol. The <b>voter_key</b> is the
  * RSA identity key fingerprint of the authority's vote from which the
  * commit comes from. The <b>phase</b> is the phase we should be validating
@@ -705,7 +705,7 @@ should_keep_commit(const sr_commit_t *commit, const char *voter_key,
   return 0;
 }
 
-/* We are in reveal phase and we found a valid and verified <b>commit</b> in
+/** We are in reveal phase and we found a valid and verified <b>commit</b> in
  * a vote that contains reveal values that we could use. Update the commit
  * we have in our state. Never call this with an unverified commit. */
 STATIC void
@@ -726,7 +726,7 @@ save_commit_during_reveal_phase(const sr_commit_t *commit)
   sr_state_copy_reveal_info(saved_commit, commit);
 }
 
-/* Save <b>commit</b> to our persistent state. Depending on the current
+/** Save <b>commit</b> to our persistent state. Depending on the current
  * phase, different actions are taken. Steals reference of <b>commit</b>.
  * The commit object MUST be valid and verified before adding it to the
  * state. */
@@ -751,7 +751,7 @@ save_commit_to_state(sr_commit_t *commit)
   }
 }
 
-/* Return 1 if we should we keep an SRV voted by <b>n_agreements</b> auths.
+/** Return 1 if we should we keep an SRV voted by <b>n_agreements</b> auths.
  * Return 0 if we should ignore it. */
 static int
 should_keep_srv(int n_agreements)
@@ -781,7 +781,7 @@ should_keep_srv(int n_agreements)
   return 1;
 }
 
-/* Helper: compare two DIGEST256_LEN digests. */
+/** Helper: compare two DIGEST256_LEN digests. */
 static int
 compare_srvs_(const void **_a, const void **_b)
 {
@@ -789,7 +789,7 @@ compare_srvs_(const void **_a, const void **_b)
   return tor_memcmp(a->value, b->value, sizeof(a->value));
 }
 
-/* Return the most frequent member of the sorted list of DIGEST256_LEN
+/** Return the most frequent member of the sorted list of DIGEST256_LEN
  * digests in <b>sl</b> with the count of that most frequent element. */
 static sr_srv_t *
 smartlist_get_most_frequent_srv(const smartlist_t *sl, int *count_out)
@@ -806,7 +806,7 @@ compare_srv_(const void **_a, const void **_b)
                      sizeof(a->value));
 }
 
-/* Using a list of <b>votes</b>, return the SRV object from them that has
+/** Using a list of <b>votes</b>, return the SRV object from them that has
  * been voted by the majority of dirauths. If <b>current</b> is set, we look
  * for the current SRV value else the previous one. The returned pointer is
  * an object located inside a vote. NULL is returned if no appropriate value
@@ -868,7 +868,7 @@ get_majority_srv_from_votes(const smartlist_t *votes, int current)
   return the_srv;
 }
 
-/* Free a commit object. */
+/** Free a commit object. */
 void
 sr_commit_free_(sr_commit_t *commit)
 {
@@ -880,7 +880,7 @@ sr_commit_free_(sr_commit_t *commit)
   tor_free(commit);
 }
 
-/* Generate the commitment/reveal value for the protocol run starting at
+/** Generate the commitment/reveal value for the protocol run starting at
  * <b>timestamp</b>. <b>my_rsa_cert</b> is our authority RSA certificate. */
 sr_commit_t *
 sr_generate_our_commit(time_t timestamp, const authority_cert_t *my_rsa_cert)
@@ -937,7 +937,8 @@ sr_generate_our_commit(time_t timestamp, const authority_cert_t *my_rsa_cert)
   return NULL;
 }
 
-/* Compute the shared random value based on the active commits in our state. */
+/** Compute the shared random value based on the active commits in our
+ * state. */
 void
 sr_compute_srv(void)
 {
@@ -1010,7 +1011,7 @@ sr_compute_srv(void)
   tor_free(reveals);
 }
 
-/* Parse a commit from a vote or from our disk state and return a newly
+/** Parse a commit from a vote or from our disk state and return a newly
  * allocated commit object. NULL is returned on error.
  *
  * The commit's data is in <b>args</b> and the order matters very much:
@@ -1082,7 +1083,7 @@ sr_parse_commit(const smartlist_t *args)
   return NULL;
 }
 
-/* Called when we are done parsing a vote by <b>voter_key</b> that might
+/** Called when we are done parsing a vote by <b>voter_key</b> that might
  * contain some useful <b>commits</b>. Find if any of them should be kept
  * and update our state accordingly. Once done, the list of commitments will
  * be empty. */
@@ -1120,7 +1121,7 @@ sr_handle_received_commits(smartlist_t *commits, crypto_pk_t *voter_key)
   } SMARTLIST_FOREACH_END(commit);
 }
 
-/* Return a heap-allocated string containing commits that should be put in
+/** Return a heap-allocated string containing commits that should be put in
  * the votes. It's the responsibility of the caller to free the string.
  * This always return a valid string, either empty or with line(s). */
 char *
@@ -1178,7 +1179,7 @@ sr_get_string_for_vote(void)
   return vote_str;
 }
 
-/* Return a heap-allocated string that should be put in the consensus and
+/** Return a heap-allocated string that should be put in the consensus and
  * contains the shared randomness values. It's the responsibility of the
  * caller to free the string. NULL is returned if no SRV(s) available.
  *
@@ -1222,7 +1223,7 @@ sr_get_string_for_consensus(const smartlist_t *votes,
   return NULL;
 }
 
-/* We just computed a new <b>consensus</b>. Update our state with the SRVs
+/** We just computed a new <b>consensus</b>. Update our state with the SRVs
  * from the consensus (might be NULL as well). Register the SRVs in our SR
  * state and prepare for the upcoming protocol round. */
 void
@@ -1261,7 +1262,7 @@ sr_act_post_consensus(const networkstatus_t *consensus)
   sr_state_update(voting_schedule_get_next_valid_after_time());
 }
 
-/* Initialize shared random subsystem. This MUST be called early in the boot
+/** Initialize shared random subsystem. This MUST be called early in the boot
  * process of tor. Return 0 on success else -1 on error. */
 int
 sr_init(int save_to_disk)
@@ -1269,7 +1270,7 @@ sr_init(int save_to_disk)
   return sr_state_init(save_to_disk, 1);
 }
 
-/* Save our state to disk and cleanup everything. */
+/** Save our state to disk and cleanup everything. */
 void
 sr_save_and_cleanup(void)
 {
@@ -1279,7 +1280,7 @@ sr_save_and_cleanup(void)
 
 #ifdef TOR_UNIT_TESTS
 
-/* Set the global value of number of SRV agreements so the test can play
+/** Set the global value of number of SRV agreements so the test can play
  * along by calling specific functions that don't parse the votes prior for
  * the AuthDirNumSRVAgreements value. */
 void
diff --git a/src/feature/dirauth/shared_random.h b/src/feature/dirauth/shared_random.h
index 7ff9f1551..b3b4b3a2a 100644
--- a/src/feature/dirauth/shared_random.h
+++ b/src/feature/dirauth/shared_random.h
@@ -4,83 +4,85 @@
 #ifndef TOR_SHARED_RANDOM_H
 #define TOR_SHARED_RANDOM_H
 
-/*
- * This file contains ABI/API of the shared random protocol defined in
+/**
+ * \file shared_random.h
+ *
+ * \brief This file contains ABI/API of the shared random protocol defined in
  * proposal #250. Every public functions and data structure are namespaced
  * with "sr_" which stands for shared random.
  */
 
 #include "core/or/or.h"
 
-/* Protocol version */
+/** Protocol version */
 #define SR_PROTO_VERSION  1
-/* Default digest algorithm. */
+/** Default digest algorithm. */
 #define SR_DIGEST_ALG DIGEST_SHA3_256
-/* Invariant token in the SRV calculation. */
+/** Invariant token in the SRV calculation. */
 #define SR_SRV_TOKEN "shared-random"
-/* Don't count the NUL terminated byte even though the TOKEN has it. */
+/** Don't count the NUL terminated byte even though the TOKEN has it. */
 #define SR_SRV_TOKEN_LEN (sizeof(SR_SRV_TOKEN) - 1)
 
-/* Length of the random number (in bytes). */
+/** Length of the random number (in bytes). */
 #define SR_RANDOM_NUMBER_LEN 32
-/* Size of a decoded commit value in a vote or state. It's a hash and a
+/** Size of a decoded commit value in a vote or state. It's a hash and a
  * timestamp. It adds up to 40 bytes. */
 #define SR_COMMIT_LEN (sizeof(uint64_t) + DIGEST256_LEN)
-/* Size of a decoded reveal value from a vote or state. It's a 64 bit
+/** Size of a decoded reveal value from a vote or state. It's a 64 bit
  * timestamp and the hashed random number. This adds up to 40 bytes. */
 #define SR_REVEAL_LEN (sizeof(uint64_t) + DIGEST256_LEN)
-/* Size of SRV message length. The construction is has follow:
+/** Size of SRV message length. The construction is has follow:
  *  "shared-random" | INT_8(reveal_num) | INT_4(version) | PREV_SRV */
 #define SR_SRV_MSG_LEN \
   (SR_SRV_TOKEN_LEN + sizeof(uint64_t) + sizeof(uint32_t) + DIGEST256_LEN)
 
-/* Length of base64 encoded commit NOT including the NUL terminated byte.
+/** Length of base64 encoded commit NOT including the NUL terminated byte.
  * Formula is taken from base64_encode_size. This adds up to 56 bytes. */
 #define SR_COMMIT_BASE64_LEN (BASE64_LEN(SR_COMMIT_LEN))
-/* Length of base64 encoded reveal NOT including the NUL terminated byte.
+/** Length of base64 encoded reveal NOT including the NUL terminated byte.
  * Formula is taken from base64_encode_size. This adds up to 56 bytes. */
 #define SR_REVEAL_BASE64_LEN (BASE64_LEN(SR_REVEAL_LEN))
-/* Length of base64 encoded shared random value. It's 32 bytes long so 44
+/** Length of base64 encoded shared random value. It's 32 bytes long so 44
  * bytes from the base64_encode_size formula. That includes the '='
  * character at the end. */
 #define SR_SRV_VALUE_BASE64_LEN (BASE64_LEN(DIGEST256_LEN))
 
-/* Assert if commit valid flag is not set. */
+/** Assert if commit valid flag is not set. */
 #define ASSERT_COMMIT_VALID(c) tor_assert((c)->valid)
 
-/* Protocol phase. */
+/** Protocol phase. */
 typedef enum {
-  /* Commitment phase */
+  /** Commitment phase */
   SR_PHASE_COMMIT  = 1,
-  /* Reveal phase */
+  /** Reveal phase */
   SR_PHASE_REVEAL  = 2,
 } sr_phase_t;
 
-/* A shared random value (SRV). */
+/** A shared random value (SRV). */
 typedef struct sr_srv_t {
-  /* The number of reveal values used to derive this SRV. */
+  /** The number of reveal values used to derive this SRV. */
   uint64_t num_reveals;
-  /* The actual value. This is the stored result of SHA3-256. */
+  /** The actual value. This is the stored result of SHA3-256. */
   uint8_t value[DIGEST256_LEN];
 } sr_srv_t;
 
-/* A commit (either ours or from another authority). */
+/** A commit (either ours or from another authority). */
 typedef struct sr_commit_t {
-  /* Hashing algorithm used. */
+  /** Hashing algorithm used. */
   digest_algorithm_t alg;
-  /* Indicate if this commit has been verified thus valid. */
+  /** Indicate if this commit has been verified thus valid. */
   unsigned int valid:1;
 
   /* Commit owner info */
 
-  /* The RSA identity key of the authority and its base16 representation,
+  /** The RSA identity key of the authority and its base16 representation,
    * which includes the NUL terminated byte. */
   char rsa_identity[DIGEST_LEN];
   char rsa_identity_hex[HEX_DIGEST_LEN + 1];
 
   /* Commitment information */
 
-  /* Timestamp of reveal. Correspond to TIMESTAMP. */
+  /** Timestamp of reveal. Correspond to TIMESTAMP. */
   uint64_t reveal_ts;
   /* H(REVEAL) as found in COMMIT message. */
   char hashed_reveal[DIGEST256_LEN];
@@ -89,13 +91,13 @@ typedef struct sr_commit_t {
 
   /* Reveal information */
 
-  /* H(RN) which is what we used as the random value for this commit. We
+  /** H(RN) which is what we used as the random value for this commit. We
    * don't use the raw bytes since those are sent on the network thus
    * avoiding possible information leaks of our PRNG. */
   uint8_t random_number[SR_RANDOM_NUMBER_LEN];
-  /* Timestamp of commit. Correspond to TIMESTAMP. */
+  /** Timestamp of commit. Correspond to TIMESTAMP. */
   uint64_t commit_ts;
-  /* This is the whole reveal message. We use it during verification */
+  /** This is the whole reveal message. We use it during verification */
   char encoded_reveal[SR_REVEAL_BASE64_LEN + 1];
 } sr_commit_t;
 
@@ -191,4 +193,3 @@ void set_num_srv_agreements(int32_t value);
 #endif /* TOR_UNIT_TESTS */
 
 #endif /* !defined(TOR_SHARED_RANDOM_H) */
-





More information about the tor-commits mailing list