src/or/dirvote.h

   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-2017, 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 /* A placeholder for routerstatus_format_entry() when the consensus method
  53  * argument is not applicable. */
  54 #define ROUTERSTATUS_FORMAT_NO_CONSENSUS_METHOD 0
  55
  56 /** The lowest consensus method that we currently support. */
  57 #define MIN_SUPPORTED_CONSENSUS_METHOD 25
  58
  59 /** The highest consensus method that we currently support. */
  60 #define MAX_SUPPORTED_CONSENSUS_METHOD 28
  61
  62 /** Lowest consensus method where authorities vote on required/recommended
  63  * protocols. */
  64 #define MIN_METHOD_FOR_RECOMMENDED_PROTOCOLS 25
  65
  66 /** Lowest consensus method where authorities add protocols to routerstatus
  67  * entries. */
  68 #define MIN_METHOD_FOR_RS_PROTOCOLS 25
  69
  70 /** Lowest consensus method where authorities initialize bandwidth weights to 1
  71  * instead of 0. See #14881 */
  72 #define MIN_METHOD_FOR_INIT_BW_WEIGHTS_ONE 26
  73
  74 /** Lowest consensus method where the microdesc consensus contains relay IPv6
  75  * addresses. See #23826 and #20916. */
  76 #define MIN_METHOD_FOR_A_LINES_IN_MICRODESC_CONSENSUS 27
  77
  78 /** Lowest consensus method where microdescriptors do not contain relay IPv6
  79  * addresses. See #23828 and #20916. */
  80 #define MIN_METHOD_FOR_NO_A_LINES_IN_MICRODESC 28
  81
  82 /** Default bandwidth to clip unmeasured bandwidths to using method >=
  83  * MIN_METHOD_TO_CLIP_UNMEASURED_BW.  (This is not a consensus method; do not
  84  * get confused with the above macros.) */
  85 #define DEFAULT_MAX_UNMEASURED_BW_KB 20
  86
  87 /* Directory Get Vote (DGV) flags for dirvote_get_vote(). */
  88 #define DGV_BY_ID 1
  89 #define DGV_INCLUDE_PENDING 2
  90 #define DGV_INCLUDE_PREVIOUS 4
  91
  92 /*
  93  * Public API. Used outside of the dirauth subsystem.
  94  */
  95
  96 void dirvote_free_all(void);
  97
  98 /* Vote manipulation */
  99 void ns_detached_signatures_free_(ns_detached_signatures_t *s);
 100 #define ns_detached_signatures_free(s) \
 101   FREE_AND_NULL(ns_detached_signatures_t, ns_detached_signatures_free_, (s))
 102
 103 void dirvote_recalculate_timing(const or_options_t *options, time_t now);
 104 void dirvote_act(const or_options_t *options, time_t now);
 105 /* Invoked on timers and by outside triggers. */
 106 struct pending_vote_t * dirvote_add_vote(const char *vote_body,
 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 /* Item access */
 113 MOCK_DECL(const char*, dirvote_get_pending_consensus,
 114           (consensus_flavor_t flav));
 115 MOCK_DECL(const char*, dirvote_get_pending_detached_signatures, (void));
 116 const cached_dir_t *dirvote_get_vote(const char *fp, int flags);
 117 document_signature_t *voter_get_sig_by_algorithm(
 118                            const networkstatus_voter_info_t *voter,
 119                            digest_algorithm_t alg);
 120
 121 /*
 122  * API used _only_ by the dirauth subsystem.
 123  */
 124
 125 /* Cert manipulation */
 126 authority_cert_t *authority_cert_dup(authority_cert_t *cert);
 127
 128 void dirvote_get_preferred_voting_intervals(vote_timing_t *timing_out);
 129 time_t dirvote_get_start_of_next_interval(time_t now,
 130                                           int interval,
 131                                           int offset);
 132 time_t dirvote_get_next_valid_after_time(void);
 133
 134 void set_routerstatus_from_routerinfo(routerstatus_t *rs,
 135                                       node_t *node,
 136                                       routerinfo_t *ri, time_t now,
 137                                       int listbadexits);
 138 networkstatus_t *
 139 dirserv_generate_networkstatus_vote_obj(crypto_pk_t *private_key,
 140                                         authority_cert_t *cert);
 141
 142 vote_microdesc_hash_t *dirvote_format_all_microdesc_vote_lines(
 143                                         const routerinfo_t *ri,
 144                                         time_t now,
 145                                         smartlist_t *microdescriptors_out);
 146
 147 /*
 148  * Exposed functions for unit tests.
 149  */
 150 #ifdef DIRVOTE_PRIVATE
 151
 152 STATIC int32_t dirvote_get_intermediate_param_value(
 153                                    const smartlist_t *param_list,
 154                                    const char *keyword,
 155                                    int32_t default_val);
 156 STATIC char *format_networkstatus_vote(crypto_pk_t *private_key,
 157                                  networkstatus_t *v3_ns);
 158 STATIC smartlist_t *dirvote_compute_params(smartlist_t *votes, int method,
 159                              int total_authorities);
 160 STATIC char *compute_consensus_package_lines(smartlist_t *votes);
 161 STATIC char *make_consensus_method_list(int low, int high, const char *sep);
 162 STATIC int
 163 networkstatus_compute_bw_weights_v10(smartlist_t *chunks, int64_t G,
 164                                      int64_t M, int64_t E, int64_t D,
 165                                      int64_t T, int64_t weight_scale);
 166 STATIC
 167 char *networkstatus_compute_consensus(smartlist_t *votes,
 168                                       int total_authorities,
 169                                       crypto_pk_t *identity_key,
 170                                       crypto_pk_t *signing_key,
 171                                       const char *legacy_identity_key_digest,
 172                                       crypto_pk_t *legacy_signing_key,
 173                                       consensus_flavor_t flavor);
 174 STATIC
 175 int networkstatus_add_detached_signatures(networkstatus_t *target,
 176                                           ns_detached_signatures_t *sigs,
 177                                           const char *source,
 178                                           int severity,
 179                                           const char **msg_out);
 180 STATIC
 181 char *networkstatus_get_detached_signatures(smartlist_t *consensuses);
 182 STATIC microdesc_t *dirvote_create_microdescriptor(const routerinfo_t *ri,
 183                                                    int consensus_method);
 184
 185 #endif /* defined(DIRVOTE_PRIVATE) */
 186
 187 #endif /* !defined(TOR_DIRVOTE_H) */
 188