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