Tor  0.4.6.0-alpha-dev
dirvote.h
Go to the documentation of this file.
1 /* Copyright (c) 2001 Matej Pfajfar.
2  * Copyright (c) 2001-2004, Roger Dingledine.
3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4  * Copyright (c) 2007-2020, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * \file dirvote.h
9  * \brief Header file for dirvote.c.
10  **/
11 
12 #ifndef TOR_DIRVOTE_H
13 #define TOR_DIRVOTE_H
14 
15 /*
16  * Ideally, assuming synced clocks, we should only need 1 second for each of:
17  * - Vote
18  * - Distribute
19  * - Consensus Publication
20  * As we can gather descriptors continuously.
21  * (Could we even go as far as publishing the previous consensus,
22  * in the same second that we vote for the next one?)
23  * But we're not there yet: these are the lowest working values at this time.
24  */
25 
26 /** Lowest allowable value for VoteSeconds. */
27 #define MIN_VOTE_SECONDS 2
28 /** Lowest allowable value for VoteSeconds when TestingTorNetwork is 1 */
29 #define MIN_VOTE_SECONDS_TESTING 2
30 
31 /** Lowest allowable value for DistSeconds. */
32 #define MIN_DIST_SECONDS 2
33 /** Lowest allowable value for DistSeconds when TestingTorNetwork is 1 */
34 #define MIN_DIST_SECONDS_TESTING 2
35 
36 /** Lowest allowable voting interval. */
37 #define MIN_VOTE_INTERVAL 300
38 /** Lowest allowable voting interval when TestingTorNetwork is 1:
39  * Voting Interval can be:
40  * 10, 12, 15, 18, 20, 24, 25, 30, 36, 40, 45, 50, 60, ...
41  * Testing Initial Voting Interval can be:
42  * 5, 6, 8, 9, or any of the possible values for Voting Interval,
43  * as they both need to evenly divide 30 minutes.
44  * If clock desynchronisation is an issue, use an interval of at least:
45  * 18 * drift in seconds, to allow for a clock slop factor */
46 #define MIN_VOTE_INTERVAL_TESTING \
47  (((MIN_VOTE_SECONDS_TESTING)+(MIN_DIST_SECONDS_TESTING)+1)*2)
48 
49 #define MIN_VOTE_INTERVAL_TESTING_INITIAL \
50  ((MIN_VOTE_SECONDS_TESTING)+(MIN_DIST_SECONDS_TESTING)+1)
51 
52 /** The lowest consensus method that we currently support. */
53 #define MIN_SUPPORTED_CONSENSUS_METHOD 28
54 
55 /** The highest consensus method that we currently support. */
56 #define MAX_SUPPORTED_CONSENSUS_METHOD 31
57 
58 /**
59  * Lowest consensus method where microdescriptor lines are put in canonical
60  * form for improved compressibility and ease of storage. See proposal 298.
61  **/
62 #define MIN_METHOD_FOR_CANONICAL_FAMILIES_IN_MICRODESCS 29
63 
64 /** Lowest consensus method where an unpadded base64 onion-key-ntor is allowed
65  * See #7869 */
66 #define MIN_METHOD_FOR_UNPADDED_NTOR_KEY 30
67 
68 /** Lowest consensus method for which we use the correct algorithm for
69  * extracting the bwweightscale= and maxunmeasuredbw= parameters. See #19011.
70  */
71 #define MIN_METHOD_FOR_CORRECT_BWWEIGHTSCALE 31
72 
73 /** Default bandwidth to clip unmeasured bandwidths to using method >=
74  * MIN_METHOD_TO_CLIP_UNMEASURED_BW. (This is not a consensus method; do not
75  * get confused with the above macros.) */
76 #define DEFAULT_MAX_UNMEASURED_BW_KB 20
77 
78 /* Directory Get Vote (DGV) flags for dirvote_get_vote(). */
79 #define DGV_BY_ID 1
80 #define DGV_INCLUDE_PENDING 2
81 #define DGV_INCLUDE_PREVIOUS 4
82 
83 /** Maximum size of a line in a vote. */
84 #define MAX_BW_FILE_HEADERS_LINE_LEN 1024
85 
86 extern const char DIRVOTE_UNIVERSAL_FLAGS[];
87 extern const char DIRVOTE_OPTIONAL_FLAGS[];
88 
89 /*
90  * Public API. Used outside of the dirauth subsystem.
91  *
92  * We need to nullify them if the module is disabled.
93  */
94 #ifdef HAVE_MODULE_DIRAUTH
95 
96 time_t dirvote_act(const or_options_t *options, time_t now);
97 void dirvote_free_all(void);
98 
99 void dirvote_parse_sr_commits(networkstatus_t *ns, const smartlist_t *tokens);
100 void dirvote_clear_commits(networkstatus_t *ns);
101 void dirvote_dirreq_get_status_vote(const char *url, smartlist_t *items,
102  smartlist_t *dir_items);
103 
104 /* Storing signatures and votes functions */
105 struct pending_vote_t * dirvote_add_vote(const char *vote_body,
106  time_t time_posted,
107  const char **msg_out,
108  int *status_out);
109 int dirvote_add_signatures(const char *detached_signatures_body,
110  const char *source,
111  const char **msg_out);
112 
113 struct config_line_t;
114 char *format_recommended_version_list(const struct config_line_t *line,
115  int warn);
116 
117 #else /* !defined(HAVE_MODULE_DIRAUTH) */
118 
119 static inline time_t
120 dirvote_act(const or_options_t *options, time_t now)
121 {
122  (void) options;
123  (void) now;
124  return TIME_MAX;
125 }
126 
127 static inline void
128 dirvote_free_all(void)
129 {
130 }
131 
132 static inline void
133 dirvote_parse_sr_commits(networkstatus_t *ns, const smartlist_t *tokens)
134 {
135  (void) ns;
136  (void) tokens;
137 }
138 
139 static inline void
140 dirvote_clear_commits(networkstatus_t *ns)
141 {
142  (void) ns;
143 }
144 
145 static inline void
146 dirvote_dirreq_get_status_vote(const char *url, smartlist_t *items,
147  smartlist_t *dir_items)
148 {
149  (void) url;
150  (void) items;
151  (void) dir_items;
152 }
153 
154 static inline struct pending_vote_t *
155 dirvote_add_vote(const char *vote_body,
156  time_t time_posted,
157  const char **msg_out,
158  int *status_out)
159 {
160  (void) vote_body;
161  (void) time_posted;
162  /* If the dirauth module is disabled, this should NEVER be called else we
163  * failed to safeguard the dirauth module. */
165 
166  /* We need to send out an error code. */
167  *status_out = 400;
168  *msg_out = "No directory authority support";
169  return NULL;
170 }
171 
172 static inline int
173 dirvote_add_signatures(const char *detached_signatures_body,
174  const char *source,
175  const char **msg_out)
176 {
177  (void) detached_signatures_body;
178  (void) source;
179  *msg_out = "No directory authority support";
180  /* If the dirauth module is disabled, this should NEVER be called else we
181  * failed to safeguard the dirauth module. */
183  return 0;
184 }
185 
186 #endif /* defined(HAVE_MODULE_DIRAUTH) */
187 
188 /* Item access */
190  (consensus_flavor_t flav));
192  (const routerinfo_t *ri));
194 const cached_dir_t *dirvote_get_vote(const char *fp, int flags);
195 
196 /*
197  * API used _only_ by the dirauth subsystem.
198  */
199 
202  authority_cert_t *cert);
203 
205  const routerinfo_t *ri,
206  time_t now,
207  smartlist_t *microdescriptors_out);
208 
209 /*
210  * Exposed functions for unit tests.
211  */
212 #ifdef DIRVOTE_PRIVATE
213 
214 /* Cert manipulation */
217  const smartlist_t *param_list,
218  const char *keyword,
219  int32_t default_val);
220 STATIC char *format_networkstatus_vote(crypto_pk_t *private_key,
221  networkstatus_t *v3_ns);
223  int total_authorities);
225 STATIC char *make_consensus_method_list(int low, int high, const char *sep);
226 STATIC int
228  int64_t M, int64_t E, int64_t D,
229  int64_t T, int64_t weight_scale);
230 STATIC
232  int total_authorities,
233  crypto_pk_t *identity_key,
234  crypto_pk_t *signing_key,
235  const char *legacy_identity_key_digest,
237  consensus_flavor_t flavor);
238 STATIC
241  const char *source,
242  int severity,
243  const char **msg_out);
244 STATIC int
246  const routerinfo_t *second);
247 STATIC
248 int compare_routerinfo_by_ipv4(const void **a, const void **b);
249 
250 STATIC
251 int compare_routerinfo_by_ipv6(const void **a, const void **b);
252 
253 STATIC
254 digestmap_t * get_sybil_list_by_ip_version(
255  const smartlist_t *routers, sa_family_t family);
256 
257 STATIC
258 digestmap_t * get_all_possible_sybil(const smartlist_t *routers);
259 
260 STATIC
263  int consensus_method);
264 STATIC int64_t extract_param_buggy(const char *params,
265  const char *param_name,
266  int64_t default_value);
267 
268 /** The recommended relay protocols for this authority's votes.
269  * Recommending a new protocol causes old tor versions to log a warning.
270  */
271 #define DIRVOTE_RECOMMEND_RELAY_PROTO \
272  "Cons=2 " \
273  "Desc=2 " \
274  "DirCache=2 " \
275  "HSDir=2 " \
276  "HSIntro=4 " \
277  "HSRend=2 " \
278  "Link=4-5 " \
279  "LinkAuth=3 " \
280  "Microdesc=2 " \
281  "Relay=2"
282 
283 /** The recommended client protocols for this authority's votes.
284  * Recommending a new protocol causes old tor versions to log a warning.
285  */
286 #define DIRVOTE_RECOMMEND_CLIENT_PROTO \
287  "Cons=2 " \
288  "Desc=2 " \
289  "DirCache=2 " \
290  "HSDir=2 " \
291  "HSIntro=4 " \
292  "HSRend=2 " \
293  "Link=4-5 " \
294  "Microdesc=2 " \
295  "Relay=2"
296 
297 /** The required relay protocols for this authority's votes.
298  * WARNING: Requiring a new protocol causes old tor versions to shut down.
299  * Requiring the wrong protocols can break the tor network.
300  * See Proposal 303: When and how to remove support for protocol versions.
301  */
302 #define DIRVOTE_REQUIRE_RELAY_PROTO \
303  "Cons=2 " \
304  "Desc=2 " \
305  "DirCache=2 " \
306  "HSDir=2 " \
307  "HSIntro=4 " \
308  "HSRend=2 " \
309  "Link=4-5 " \
310  "LinkAuth=3 " \
311  "Microdesc=2 " \
312  "Relay=2"
313 
314 /** The required relay protocols for this authority's votes.
315  * WARNING: Requiring a new protocol causes old tor versions to shut down.
316  * Requiring the wrong protocols can break the tor network.
317  * See Proposal 303: When and how to remove support for protocol versions.
318  */
319 #define DIRVOTE_REQUIRE_CLIENT_PROTO \
320  "Cons=2 " \
321  "Desc=2 " \
322  "Link=4 " \
323  "Microdesc=2 " \
324  "Relay=2"
325 
326 #endif /* defined(DIRVOTE_PRIVATE) */
327 
328 #endif /* !defined(TOR_DIRVOTE_H) */
microdesc_t
Definition: microdesc_st.h:27
compare_routerinfo_usefulness
STATIC int compare_routerinfo_usefulness(const routerinfo_t *first, const routerinfo_t *second)
Definition: dirvote.c:4280
routerinfo_t
Definition: routerinfo_st.h:20
T
#define T(s, t, a, o)
Definition: parsecommon.h:246
get_sybil_list_by_ip_version
STATIC digestmap_t * get_sybil_list_by_ip_version(const smartlist_t *routers, sa_family_t family)
Definition: dirvote.c:4330
vote_microdesc_hash_t
Definition: vote_microdesc_hash_st.h:18
dirvote_get_pending_consensus
const char * dirvote_get_pending_consensus(consensus_flavor_t flav)
Definition: dirvote.c:3777
dirvote_add_vote
pending_vote_t * dirvote_add_vote(const char *vote_body, time_t time_posted, const char **msg_out, int *status_out)
Definition: dirvote.c:3184
pending_vote_t
Definition: dirvote.c:2938
dirvote_act
time_t dirvote_act(const or_options_t *options, time_t now)
Definition: dirvote.c:2861
dirvote_get_pending_detached_signatures
const char * dirvote_get_pending_detached_signatures(void)
Definition: dirvote.c:3786
consensus_flavor_t
consensus_flavor_t
Definition: or.h:881
get_all_possible_sybil
STATIC digestmap_t * get_all_possible_sybil(const smartlist_t *routers)
Definition: dirvote.c:4370
make_consensus_method_list
STATIC char * make_consensus_method_list(int low, int high, const char *separator)
Definition: dirvote.c:836
compare_routerinfo_by_ipv4
STATIC int compare_routerinfo_by_ipv4(const void **a, const void **b)
Definition: dirvote.c:4243
tor_assert_nonfatal_unreached
#define tor_assert_nonfatal_unreached()
Definition: util_bug.h:176
authority_cert_dup
STATIC authority_cert_t * authority_cert_dup(authority_cert_t *cert)
Definition: dirvote.c:146
DIRVOTE_OPTIONAL_FLAGS
const char DIRVOTE_OPTIONAL_FLAGS[]
Definition: dirvote.c:4556
compare_routerinfo_by_ipv6
STATIC int compare_routerinfo_by_ipv6(const void **a, const void **b)
Definition: dirvote.c:4261
dirserv_get_bandwidth_for_router_kb
uint32_t dirserv_get_bandwidth_for_router_kb(const routerinfo_t *ri)
Definition: dirvote.c:4195
dirserv_generate_networkstatus_vote_obj
networkstatus_t * dirserv_generate_networkstatus_vote_obj(crypto_pk_t *private_key, authority_cert_t *cert)
Definition: dirvote.c:4563
legacy_signing_key
static crypto_pk_t * legacy_signing_key
Definition: router.c:131
MOCK_DECL
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
cached_dir_t
Definition: cached_dir_st.h:17
authority_cert_t
Definition: authority_cert_st.h:19
dirvote_get_vote
const cached_dir_t * dirvote_get_vote(const char *fp, int flags)
Definition: dirvote.c:3800
networkstatus_compute_bw_weights_v10
int networkstatus_compute_bw_weights_v10(smartlist_t *chunks, int64_t G, int64_t M, int64_t E, int64_t D, int64_t T, int64_t weight_scale)
Definition: dirvote.c:1097
dirvote_format_all_microdesc_vote_lines
vote_microdesc_hash_t * dirvote_format_all_microdesc_vote_lines(const routerinfo_t *ri, time_t now, smartlist_t *microdescriptors_out)
Definition: dirvote.c:3998
dirvote_create_microdescriptor
STATIC microdesc_t * dirvote_create_microdescriptor(const routerinfo_t *ri, int consensus_method)
Definition: dirvote.c:3846
dirvote_free_all
void dirvote_free_all(void)
Definition: dirvote.c:3753
networkstatus_add_detached_signatures
STATIC int networkstatus_add_detached_signatures(networkstatus_t *target, ns_detached_signatures_t *sigs, const char *source, int severity, const char **msg_out)
Definition: dirvote.c:2559
crypto_pk_t
Definition: crypto_rsa_nss.c:37
dirvote_compute_params
STATIC smartlist_t * dirvote_compute_params(smartlist_t *votes, int method, int total_authorities)
Definition: dirvote.c:921
format_recommended_version_list
char * format_recommended_version_list(const config_line_t *ln, int warn)
Definition: dirvote.c:4433
config_line_t
Definition: confline.h:29
DIRVOTE_UNIVERSAL_FLAGS
const char DIRVOTE_UNIVERSAL_FLAGS[]
Definition: dirvote.c:4544
dirvote_get_intermediate_param_value
STATIC int32_t dirvote_get_intermediate_param_value(const smartlist_t *param_list, const char *keyword, int32_t default_val)
Definition: dirvote.c:885
networkstatus_compute_consensus
STATIC char * networkstatus_compute_consensus(smartlist_t *votes, int total_authorities, crypto_pk_t *identity_key, crypto_pk_t *signing_key, const char *legacy_id_key_digest, crypto_pk_t *legacy_signing_key, consensus_flavor_t flavor)
Definition: dirvote.c:1502
format_networkstatus_vote
STATIC char * format_networkstatus_vote(crypto_pk_t *private_signing_key, networkstatus_t *v3_ns)
Definition: dirvote.c:223
sa_family_t
uint16_t sa_family_t
Definition: inaddr_st.h:77
or_options_t
Definition: or_options_st.h:64
STATIC
#define STATIC
Definition: testsupport.h:32
extract_param_buggy
STATIC int64_t extract_param_buggy(const char *params, const char *param_name, int64_t default_value)
Definition: dirvote.c:2436
compute_consensus_package_lines
STATIC char * compute_consensus_package_lines(smartlist_t *votes)
Definition: dirvote.c:2478
ns_detached_signatures_t
Definition: ns_detached_signatures_st.h:17
networkstatus_t
Definition: networkstatus_st.h:26
smartlist_t
Definition: smartlist_core.h:26
networkstatus_get_detached_signatures
STATIC char * networkstatus_get_detached_signatures(smartlist_t *consensuses)
Definition: dirvote.c:2751
dirvote_add_signatures
int dirvote_add_signatures(const char *detached_signatures_body, const char *source, const char **msg)
Definition: dirvote.c:3700