src/feature/dirauth/shared_random_state.h

   1 /* Copyright (c) 2016-2021, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /**
   5  * @file shared_random_state.h
   6  * @brief Header for shared_random_state.c
   7  **/
   8
   9 #ifndef TOR_SHARED_RANDOM_STATE_H
  10 #define TOR_SHARED_RANDOM_STATE_H
  11
  12 #include "feature/dirauth/shared_random.h"
  13
  14 /** Action that can be performed on the state for any objects. */
  15 typedef enum {
  16   SR_STATE_ACTION_GET     = 1,
  17   SR_STATE_ACTION_PUT     = 2,
  18   SR_STATE_ACTION_DEL     = 3,
  19   SR_STATE_ACTION_DEL_ALL = 4,
  20   SR_STATE_ACTION_SAVE    = 5,
  21 } sr_state_action_t;
  22
  23 /** Object in the state that can be queried through the state API. */
  24 typedef enum {
  25   /** Will return a single commit using an authority identity key. */
  26   SR_STATE_OBJ_COMMIT,
  27   /** Returns the entire list of commits from the state. */
  28   SR_STATE_OBJ_COMMITS,
  29   /** Return the current SRV object pointer. */
  30   SR_STATE_OBJ_CURSRV,
  31   /** Return the previous SRV object pointer. */
  32   SR_STATE_OBJ_PREVSRV,
  33   /** Return the phase. */
  34   SR_STATE_OBJ_PHASE,
  35   /** Get or Put the valid after time. */
  36   SR_STATE_OBJ_VALID_AFTER,
  37 } sr_state_object_t;
  38
  39 /** State of the protocol. It's also saved on disk in fname. This data
  40  * structure MUST be synchronized at all time with the one on disk. */
  41 typedef struct sr_state_t {
  42   /** Filename of the state file on disk. */
  43   char *fname;
  44   /** Version of the protocol. */
  45   uint32_t version;
  46   /** The valid-after of the voting period we have prepared the state for. */
  47   time_t valid_after;
  48   /** Until when is this state valid? */
  49   time_t valid_until;
  50   /** Protocol phase. */
  51   sr_phase_t phase;
  52
  53   /** Number of runs completed. */
  54   uint64_t n_protocol_runs;
  55   /** The number of commitment rounds we've performed in this protocol run. */
  56   unsigned int n_commit_rounds;
  57   /** The number of reveal rounds we've performed in this protocol run. */
  58   unsigned int n_reveal_rounds;
  59
  60   /** A map of all the received commitments for this protocol run. This is
  61    * indexed by authority RSA identity digest. */
  62   digestmap_t *commits;
  63
  64   /** Current shared random value. */
  65   sr_srv_t *previous_srv;
  66   /** Previous shared random value. */
  67   sr_srv_t *current_srv;
  68
  69   /** Indicate if the state contains an SRV that was _just_ generated. This is
  70    * used during voting so that we know whether to use the super majority rule
  71    * or not when deciding on keeping it for the consensus. It is _always_ set
  72    * to 0 post consensus.
  73    *
  74    * EDGE CASE: if an authority computes a new SRV then immediately reboots
  75    * and, once back up, votes for the current round, it won't know if the
  76    * SRV is fresh or not ultimately making it _NOT_ use the super majority
  77    * when deciding to put or not the SRV in the consensus. This is for now
  78    * an acceptable very rare edge case. */
  79   unsigned int is_srv_fresh:1;
  80 } sr_state_t;
  81
  82 /** Persistent state of the protocol, as saved to disk. */
  83 typedef struct sr_disk_state_t {
  84   uint32_t magic_;
  85   /** Version of the protocol. */
  86   int Version;
  87   /** Version of our running tor. */
  88   char *TorVersion;
  89   /** Creation time of this state */
  90   time_t ValidAfter;
  91   /** State valid until? */
  92   time_t ValidUntil;
  93   /** All commits seen that are valid. */
  94   struct config_line_t *Commit;
  95   /** Previous and current shared random value. */
  96   struct config_line_t *SharedRandValues;
  97   /** Extra Lines for configuration we might not know. */
  98   struct config_line_t *ExtraLines;
  99 } sr_disk_state_t;
 100
 101 /* API */
 102
 103 /* Public methods: */
 104
 105 void sr_state_update(time_t valid_after);
 106
 107 /* Private methods (only used by shared-random.c): */
 108
 109 void sr_state_set_valid_after(time_t valid_after);
 110 sr_phase_t sr_state_get_phase(void);
 111 const sr_srv_t *sr_state_get_previous_srv(void);
 112 const sr_srv_t *sr_state_get_current_srv(void);
 113 void sr_state_set_previous_srv(const sr_srv_t *srv);
 114 void sr_state_set_current_srv(const sr_srv_t *srv);
 115 void sr_state_clean_srvs(void);
 116 digestmap_t *sr_state_get_commits(void);
 117 sr_commit_t *sr_state_get_commit(const char *rsa_fpr);
 118 void sr_state_add_commit(sr_commit_t *commit);
 119 void sr_state_delete_commits(void);
 120 void sr_state_copy_reveal_info(sr_commit_t *saved_commit,
 121                                const sr_commit_t *commit);
 122 unsigned int sr_state_srv_is_fresh(void);
 123 void sr_state_set_fresh_srv(void);
 124 void sr_state_unset_fresh_srv(void);
 125 int sr_state_init(int save_to_disk, int read_from_disk);
 126 int sr_state_is_initialized(void);
 127 void sr_state_save(void);
 128 void sr_state_free_all(void);
 129
 130 #ifdef SHARED_RANDOM_STATE_PRIVATE
 131
 132 STATIC int disk_state_load_from_disk_impl(const char *fname);
 133
 134 STATIC sr_phase_t get_sr_protocol_phase(time_t valid_after);
 135
 136 STATIC time_t get_state_valid_until_time(time_t now);
 137 STATIC const char *get_phase_str(sr_phase_t phase);
 138 STATIC void reset_state_for_new_protocol_run(time_t valid_after);
 139 STATIC void new_protocol_run(time_t valid_after);
 140 STATIC void state_rotate_srv(void);
 141 STATIC int is_phase_transition(sr_phase_t next_phase);
 142
 143 #endif /* defined(SHARED_RANDOM_STATE_PRIVATE) */
 144
 145 #ifdef TOR_UNIT_TESTS
 146
 147 STATIC void set_sr_phase(sr_phase_t phase);
 148 STATIC sr_state_t *get_sr_state(void);
 149 STATIC void state_del_previous_srv(void);
 150 STATIC void state_del_current_srv(void);
 151
 152 #endif /* defined(TOR_UNIT_TESTS) */
 153
 154 #endif /* !defined(TOR_SHARED_RANDOM_STATE_H) */