Tor  0.4.4.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 29
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 /** Default bandwidth to clip unmeasured bandwidths to using method >=
65  * MIN_METHOD_TO_CLIP_UNMEASURED_BW. (This is not a consensus method; do not
66  * get confused with the above macros.) */
67 #define DEFAULT_MAX_UNMEASURED_BW_KB 20
68 
69 /* Directory Get Vote (DGV) flags for dirvote_get_vote(). */
70 #define DGV_BY_ID 1
71 #define DGV_INCLUDE_PENDING 2
72 #define DGV_INCLUDE_PREVIOUS 4
73 
74 /** Maximum size of a line in a vote. */
75 #define MAX_BW_FILE_HEADERS_LINE_LEN 1024
76 
77 extern const char DIRVOTE_UNIVERSAL_FLAGS[];
78 extern const char DIRVOTE_OPTIONAL_FLAGS[];
79 
80 /*
81  * Public API. Used outside of the dirauth subsystem.
82  *
83  * We need to nullify them if the module is disabled.
84  */
85 #ifdef HAVE_MODULE_DIRAUTH
86 
87 time_t dirvote_act(const or_options_t *options, time_t now);
88 void dirvote_free_all(void);
89 
90 void dirvote_parse_sr_commits(networkstatus_t *ns, const smartlist_t *tokens);
91 void dirvote_clear_commits(networkstatus_t *ns);
92 void dirvote_dirreq_get_status_vote(const char *url, smartlist_t *items,
93  smartlist_t *dir_items);
94 
95 /* Storing signatures and votes functions */
96 struct pending_vote_t * dirvote_add_vote(const char *vote_body,
97  time_t time_posted,
98  const char **msg_out,
99  int *status_out);
100 int dirvote_add_signatures(const char *detached_signatures_body,
101  const char *source,
102  const char **msg_out);
103 
104 struct config_line_t;
105 char *format_recommended_version_list(const struct config_line_t *line,
106  int warn);
107 
108 #else /* !defined(HAVE_MODULE_DIRAUTH) */
109 
110 static inline time_t
111 dirvote_act(const or_options_t *options, time_t now)
112 {
113  (void) options;
114  (void) now;
115  return TIME_MAX;
116 }
117 
118 static inline void
119 dirvote_free_all(void)
120 {
121 }
122 
123 static inline void
124 dirvote_parse_sr_commits(networkstatus_t *ns, const smartlist_t *tokens)
125 {
126  (void) ns;
127  (void) tokens;
128 }
129 
130 static inline void
131 dirvote_clear_commits(networkstatus_t *ns)
132 {
133  (void) ns;
134 }
135 
136 static inline void
137 dirvote_dirreq_get_status_vote(const char *url, smartlist_t *items,
138  smartlist_t *dir_items)
139 {
140  (void) url;
141  (void) items;
142  (void) dir_items;
143 }
144 
145 static inline struct pending_vote_t *
146 dirvote_add_vote(const char *vote_body,
147  time_t time_posted,
148  const char **msg_out,
149  int *status_out)
150 {
151  (void) vote_body;
152  (void) time_posted;
153  /* If the dirauth module is disabled, this should NEVER be called else we
154  * failed to safeguard the dirauth module. */
155  tor_assert_nonfatal_unreached();
156 
157  /* We need to send out an error code. */
158  *status_out = 400;
159  *msg_out = "No directory authority support";
160  return NULL;
161 }
162 
163 static inline int
164 dirvote_add_signatures(const char *detached_signatures_body,
165  const char *source,
166  const char **msg_out)
167 {
168  (void) detached_signatures_body;
169  (void) source;
170  (void) msg_out;
171  /* If the dirauth module is disabled, this should NEVER be called else we
172  * failed to safeguard the dirauth module. */
173  tor_assert_nonfatal_unreached();
174  return 0;
175 }
176 
177 #endif /* defined(HAVE_MODULE_DIRAUTH) */
178 
179 /* Item access */
181  (consensus_flavor_t flav));
183 const cached_dir_t *dirvote_get_vote(const char *fp, int flags);
184 
185 /*
186  * API used _only_ by the dirauth subsystem.
187  */
188 
191  authority_cert_t *cert);
192 
194  const routerinfo_t *ri,
195  time_t now,
196  smartlist_t *microdescriptors_out);
197 
198 /*
199  * Exposed functions for unit tests.
200  */
201 #ifdef DIRVOTE_PRIVATE
202 
203 /* Cert manipulation */
206  const smartlist_t *param_list,
207  const char *keyword,
208  int32_t default_val);
209 STATIC char *format_networkstatus_vote(crypto_pk_t *private_key,
210  networkstatus_t *v3_ns);
212  int total_authorities);
214 STATIC char *make_consensus_method_list(int low, int high, const char *sep);
215 STATIC int
217  int64_t M, int64_t E, int64_t D,
218  int64_t T, int64_t weight_scale);
219 STATIC
221  int total_authorities,
222  crypto_pk_t *identity_key,
223  crypto_pk_t *signing_key,
224  const char *legacy_identity_key_digest,
226  consensus_flavor_t flavor);
227 STATIC
230  const char *source,
231  int severity,
232  const char **msg_out);
233 STATIC
236  int consensus_method);
237 
238 /** The recommended relay protocols for this authority's votes.
239  * Recommending a new protocol causes old tor versions to log a warning.
240  */
241 #define DIRVOTE_RECCOMEND_RELAY_PROTO \
242  "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
243  "Link=4 Microdesc=1-2 Relay=2"
244 /** The recommended client protocols for this authority's votes.
245  * Recommending a new protocol causes old tor versions to log a warning.
246  */
247 #define DIRVOTE_RECCOMEND_CLIENT_PROTO \
248  "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
249  "Link=4 Microdesc=1-2 Relay=2"
250 
251 /** The required relay protocols for this authority's votes.
252  * WARNING: Requiring a new protocol causes old tor versions to shut down.
253  * Requiring the wrong protocols can break the tor network.
254  * See Proposal 303: When and how to remove support for protocol versions.
255  */
256 #define DIRVOTE_REQUIRE_RELAY_PROTO \
257  "Cons=1 Desc=1 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
258  "Link=3-4 Microdesc=1 Relay=1-2"
259 /** The required relay protocols for this authority's votes.
260  * WARNING: Requiring a new protocol causes old tor versions to shut down.
261  * Requiring the wrong protocols can break the tor network.
262  * See Proposal 303: When and how to remove support for protocol versions.
263  */
264 #define DIRVOTE_REQUIRE_CLIENT_PROTO \
265  "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
266  "Link=4 Microdesc=1-2 Relay=2"
267 
268 #endif /* defined(DIRVOTE_PRIVATE) */
269 
270 #endif /* !defined(TOR_DIRVOTE_H) */
STATIC char * networkstatus_get_detached_signatures(smartlist_t *consensuses)
Definition: dirvote.c:2726
pending_vote_t * dirvote_add_vote(const char *vote_body, time_t time_posted, const char **msg_out, int *status_out)
Definition: dirvote.c:3159
STATIC char * compute_consensus_package_lines(smartlist_t *votes)
Definition: dirvote.c:2456
time_t dirvote_act(const or_options_t *options, time_t now)
Definition: dirvote.c:2836
const char * dirvote_get_pending_consensus(consensus_flavor_t flav)
Definition: dirvote.c:3739
const char * dirvote_get_pending_detached_signatures(void)
Definition: dirvote.c:3748
#define STATIC
Definition: testsupport.h:32
networkstatus_t * dirserv_generate_networkstatus_vote_obj(crypto_pk_t *private_key, authority_cert_t *cert)
Definition: dirvote.c:4436
STATIC char * make_consensus_method_list(int low, int high, const char *separator)
Definition: dirvote.c:827
STATIC authority_cert_t * authority_cert_dup(authority_cert_t *cert)
Definition: dirvote.c:144
const char DIRVOTE_OPTIONAL_FLAGS[]
Definition: dirvote.c:4429
void dirvote_free_all(void)
Definition: dirvote.c:3715
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:2534
STATIC microdesc_t * dirvote_create_microdescriptor(const routerinfo_t *ri, int consensus_method)
Definition: dirvote.c:3808
vote_microdesc_hash_t * dirvote_format_all_microdesc_vote_lines(const routerinfo_t *ri, time_t now, smartlist_t *microdescriptors_out)
Definition: dirvote.c:3959
consensus_flavor_t
Definition: or.h:867
STATIC int32_t dirvote_get_intermediate_param_value(const smartlist_t *param_list, const char *keyword, int32_t default_val)
Definition: dirvote.c:876
const cached_dir_t * dirvote_get_vote(const char *fp, int flags)
Definition: dirvote.c:3762
STATIC char * format_networkstatus_vote(crypto_pk_t *private_signing_key, networkstatus_t *v3_ns)
Definition: dirvote.c:221
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
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:1088
const char DIRVOTE_UNIVERSAL_FLAGS[]
Definition: dirvote.c:4417
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:1493
int dirvote_add_signatures(const char *detached_signatures_body, const char *source, const char **msg)
Definition: dirvote.c:3662
STATIC smartlist_t * dirvote_compute_params(smartlist_t *votes, int method, int total_authorities)
Definition: dirvote.c:912
static crypto_pk_t * legacy_signing_key
Definition: router.c:127
char * format_recommended_version_list(const config_line_t *ln, int warn)
Definition: dirvote.c:4306
#define T(s, t, a, o)
Definition: parsecommon.h:246