shared_random.[ch]: repair doxygen comments

This commit is contained in:
Nick Mathewson 2019-10-16 12:04:53 -04:00
parent 17b88241db
commit 18ea8855f2
2 changed files with 69 additions and 67 deletions

View File

@ -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

View File

@ -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) */