Tor  0.4.7.0-alpha-dev
shared_random.h
Go to the documentation of this file.
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 */
57  /** Reveal phase */
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. */
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. */
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. */
98  /** Timestamp of commit. Correspond to TIMESTAMP. */
99  uint64_t commit_ts;
100  /** This is the whole reveal message. We use it during verification */
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
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 
141  crypto_pk_t *voter_key);
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 
175  int current);
176 
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);
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) */
digest_algorithm_t
Definition: crypto_digest.h:44
#define HEX_DIGEST_LEN
Definition: crypto_digest.h:35
#define DIGEST_LEN
Definition: digest_sizes.h:20
#define DIGEST256_LEN
Definition: digest_sizes.h:23
Master header file for Tor-specific functionality.
STATIC void save_commit_during_reveal_phase(const sr_commit_t *commit)
STATIC int reveal_encode(const sr_commit_t *commit, char *dst, size_t len)
void sr_save_and_cleanup(void)
STATIC int should_keep_commit(const sr_commit_t *commit, const char *voter_key, sr_phase_t phase)
int sr_init(int save_to_disk)
STATIC int commit_is_authoritative(const sr_commit_t *commit, const char *voter_key)
void sr_act_post_consensus(const networkstatus_t *consensus)
STATIC void save_commit_to_state(sr_commit_t *commit)
STATIC int commit_has_reveal_value(const sr_commit_t *commit)
STATIC int reveal_decode(const char *encoded, sr_commit_t *commit)
STATIC int commit_encode(const sr_commit_t *commit, char *dst, size_t len)
STATIC int commitments_are_the_same(const sr_commit_t *commit_one, const sr_commit_t *commit_two)
STATIC int verify_commit_and_reveal(const sr_commit_t *commit)
STATIC int commit_decode(const char *encoded, sr_commit_t *commit)
STATIC sr_srv_t * get_majority_srv_from_votes(const smartlist_t *votes, int current)
char * sr_get_string_for_consensus(const smartlist_t *votes, int32_t num_srv_agreements)
sr_commit_t * sr_generate_our_commit(time_t timestamp, const authority_cert_t *my_rsa_cert)
sr_commit_t * sr_parse_commit(const smartlist_t *args)
#define SR_REVEAL_BASE64_LEN
Definition: shared_random.h:44
sr_phase_t
Definition: shared_random.h:54
@ SR_PHASE_COMMIT
Definition: shared_random.h:56
@ SR_PHASE_REVEAL
Definition: shared_random.h:58
sr_srv_t * sr_srv_dup(const sr_srv_t *orig)
void sr_handle_received_commits(smartlist_t *commits, crypto_pk_t *voter_key)
char * sr_get_string_for_vote(void)
void sr_compute_srv(void)
#define SR_COMMIT_BASE64_LEN
Definition: shared_random.h:41
#define SR_RANDOM_NUMBER_LEN
Definition: shared_random.h:27
void sr_commit_free_(sr_commit_t *commit)
char rsa_identity[DIGEST_LEN]
Definition: shared_random.h:80
char encoded_reveal[SR_REVEAL_BASE64_LEN+1]
uint8_t random_number[SR_RANDOM_NUMBER_LEN]
Definition: shared_random.h:97
unsigned int valid
Definition: shared_random.h:74
uint64_t reveal_ts
Definition: shared_random.h:86
digest_algorithm_t alg
Definition: shared_random.h:72
uint64_t commit_ts
Definition: shared_random.h:99
uint64_t num_reveals
Definition: shared_random.h:64
uint8_t value[DIGEST256_LEN]
Definition: shared_random.h:66
#define STATIC
Definition: testsupport.h:32