shared_random.h (6678B)
1 /* Copyright (c) 2016-2021, The Tor Project, Inc. */ 2 /* See LICENSE for licensing information */ 3 4 #ifndef TOR_SHARED_RANDOM_H 5 #define TOR_SHARED_RANDOM_H 6 7 /** 8 * \file shared_random.h 9 * 10 * \brief This file contains ABI/API of the shared random protocol defined in 11 * proposal #250. Every public functions and data structure are namespaced 12 * with "sr_" which stands for shared random. 13 */ 14 15 #include "core/or/or.h" 16 17 /** Protocol version */ 18 #define SR_PROTO_VERSION 1 19 /** Default digest algorithm. */ 20 #define SR_DIGEST_ALG DIGEST_SHA3_256 21 /** Invariant token in the SRV calculation. */ 22 #define SR_SRV_TOKEN "shared-random" 23 /** Don't count the NUL terminated byte even though the TOKEN has it. */ 24 #define SR_SRV_TOKEN_LEN (sizeof(SR_SRV_TOKEN) - 1) 25 26 /** Length of the random number (in bytes). */ 27 #define SR_RANDOM_NUMBER_LEN 32 28 /** Size of a decoded commit value in a vote or state. It's a hash and a 29 * timestamp. It adds up to 40 bytes. */ 30 #define SR_COMMIT_LEN (sizeof(uint64_t) + DIGEST256_LEN) 31 /** Size of a decoded reveal value from a vote or state. It's a 64 bit 32 * timestamp and the hashed random number. This adds up to 40 bytes. */ 33 #define SR_REVEAL_LEN (sizeof(uint64_t) + DIGEST256_LEN) 34 /** Size of SRV message length. The construction is has follow: 35 * "shared-random" | INT_8(reveal_num) | INT_4(version) | PREV_SRV */ 36 #define SR_SRV_MSG_LEN \ 37 (SR_SRV_TOKEN_LEN + sizeof(uint64_t) + sizeof(uint32_t) + DIGEST256_LEN) 38 39 /** Length of base64 encoded commit NOT including the NUL terminated byte. 40 * Formula is taken from base64_encode_size. This adds up to 56 bytes. */ 41 #define SR_COMMIT_BASE64_LEN (BASE64_LEN(SR_COMMIT_LEN)) 42 /** Length of base64 encoded reveal NOT including the NUL terminated byte. 43 * Formula is taken from base64_encode_size. This adds up to 56 bytes. */ 44 #define SR_REVEAL_BASE64_LEN (BASE64_LEN(SR_REVEAL_LEN)) 45 /** Length of base64 encoded shared random value. It's 32 bytes long so 44 46 * bytes from the base64_encode_size formula. That includes the '=' 47 * character at the end. */ 48 #define SR_SRV_VALUE_BASE64_LEN (BASE64_LEN(DIGEST256_LEN)) 49 50 /** Assert if commit valid flag is not set. */ 51 #define ASSERT_COMMIT_VALID(c) tor_assert((c)->valid) 52 53 /** Protocol phase. */ 54 typedef enum { 55 /** Commitment phase */ 56 SR_PHASE_COMMIT = 1, 57 /** Reveal phase */ 58 SR_PHASE_REVEAL = 2, 59 } sr_phase_t; 60 61 /** A shared random value (SRV). */ 62 typedef struct sr_srv_t { 63 /** The number of reveal values used to derive this SRV. */ 64 uint64_t num_reveals; 65 /** The actual value. This is the stored result of SHA3-256. */ 66 uint8_t value[DIGEST256_LEN]; 67 } sr_srv_t; 68 69 /** A commit (either ours or from another authority). */ 70 typedef struct sr_commit_t { 71 /** Hashing algorithm used. */ 72 digest_algorithm_t alg; 73 /** Indicate if this commit has been verified thus valid. */ 74 unsigned int valid:1; 75 76 /* Commit owner info */ 77 78 /** The RSA identity key of the authority and its base16 representation, 79 * which includes the NUL terminated byte. */ 80 char rsa_identity[DIGEST_LEN]; 81 char rsa_identity_hex[HEX_DIGEST_LEN + 1]; 82 83 /* Commitment information */ 84 85 /** Timestamp of reveal. Correspond to TIMESTAMP. */ 86 uint64_t reveal_ts; 87 /* H(REVEAL) as found in COMMIT message. */ 88 char hashed_reveal[DIGEST256_LEN]; 89 /* Base64 encoded COMMIT. We use this to put it in our vote. */ 90 char encoded_commit[SR_COMMIT_BASE64_LEN + 1]; 91 92 /* Reveal information */ 93 94 /** H(RN) which is what we used as the random value for this commit. We 95 * don't use the raw bytes since those are sent on the network thus 96 * avoiding possible information leaks of our PRNG. */ 97 uint8_t random_number[SR_RANDOM_NUMBER_LEN]; 98 /** Timestamp of commit. Correspond to TIMESTAMP. */ 99 uint64_t commit_ts; 100 /** This is the whole reveal message. We use it during verification */ 101 char encoded_reveal[SR_REVEAL_BASE64_LEN + 1]; 102 } sr_commit_t; 103 104 /* API */ 105 106 /* Public methods used _outside_ of the module. 107 * 108 * We need to nullify them if the module is disabled. */ 109 #ifdef HAVE_MODULE_DIRAUTH 110 111 int sr_init(int save_to_disk); 112 void sr_save_and_cleanup(void); 113 void sr_act_post_consensus(const networkstatus_t *consensus); 114 115 #else /* !defined(HAVE_MODULE_DIRAUTH) */ 116 117 static inline int 118 sr_init(int save_to_disk) 119 { 120 (void) save_to_disk; 121 /* Always return success. */ 122 return 0; 123 } 124 125 static inline void 126 sr_save_and_cleanup(void) 127 { 128 } 129 130 static inline void 131 sr_act_post_consensus(const networkstatus_t *consensus) 132 { 133 (void) consensus; 134 } 135 136 #endif /* defined(HAVE_MODULE_DIRAUTH) */ 137 138 /* Public methods used only by dirauth code. */ 139 140 void sr_handle_received_commits(smartlist_t *commits, 141 crypto_pk_t *voter_key); 142 sr_commit_t *sr_parse_commit(const smartlist_t *args); 143 char *sr_get_string_for_vote(void); 144 char *sr_get_string_for_consensus(const smartlist_t *votes, 145 int32_t num_srv_agreements); 146 void sr_commit_free_(sr_commit_t *commit); 147 #define sr_commit_free(sr) FREE_AND_NULL(sr_commit_t, sr_commit_free_, (sr)) 148 149 /* Private methods (only used by shared_random_state.c): */ 150 static inline 151 const char *sr_commit_get_rsa_fpr(const sr_commit_t *commit) 152 { 153 return commit->rsa_identity_hex; 154 } 155 156 void sr_compute_srv(void); 157 sr_commit_t *sr_generate_our_commit(time_t timestamp, 158 const authority_cert_t *my_rsa_cert); 159 sr_srv_t *sr_srv_dup(const sr_srv_t *orig); 160 161 #ifdef SHARED_RANDOM_PRIVATE 162 163 /* Encode */ 164 STATIC int reveal_encode(const sr_commit_t *commit, char *dst, size_t len); 165 STATIC int commit_encode(const sr_commit_t *commit, char *dst, size_t len); 166 /* Decode. */ 167 STATIC int commit_decode(const char *encoded, sr_commit_t *commit); 168 STATIC int reveal_decode(const char *encoded, sr_commit_t *commit); 169 170 STATIC int commit_has_reveal_value(const sr_commit_t *commit); 171 172 STATIC int verify_commit_and_reveal(const sr_commit_t *commit); 173 174 STATIC sr_srv_t *get_majority_srv_from_votes(const smartlist_t *votes, 175 int current); 176 177 STATIC void save_commit_to_state(sr_commit_t *commit); 178 STATIC int commitments_are_the_same(const sr_commit_t *commit_one, 179 const sr_commit_t *commit_two); 180 STATIC int commit_is_authoritative(const sr_commit_t *commit, 181 const char *voter_key); 182 STATIC int should_keep_commit(const sr_commit_t *commit, 183 const char *voter_key, 184 sr_phase_t phase); 185 STATIC void save_commit_during_reveal_phase(const sr_commit_t *commit); 186 187 #endif /* defined(SHARED_RANDOM_PRIVATE) */ 188 189 #ifdef TOR_UNIT_TESTS 190 191 void set_num_srv_agreements(int32_t value); 192 193 #endif /* TOR_UNIT_TESTS */ 194 195 #endif /* !defined(TOR_SHARED_RANDOM_H) */