Tor  0.4.4.0-alpha-dev
shared_random_state.h
Go to the documentation of this file.
1 /* Copyright (c) 2016-2020, 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 
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,
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. */
27  /** Returns the entire list of commits from the state. */
29  /** Return the current SRV object pointer. */
31  /** Return the previous SRV object pointer. */
33  /** Return the phase. */
35  /** Get or Put the valid after time. */
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. */
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. */
66  /** Previous shared random value. */
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. */
95  /** Previous and current shared random value. */
97  /** Extra Lines for configuration we might not know. */
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);
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) */
void sr_state_unset_fresh_srv(void)
void sr_state_save(void)
STATIC int disk_state_load_from_disk_impl(const char *fname)
STATIC void state_del_previous_srv(void)
sr_phase_t phase
void sr_state_add_commit(sr_commit_t *commit)
STATIC void state_rotate_srv(void)
int sr_state_init(int save_to_disk, int read_from_disk)
digestmap_t * commits
void sr_state_copy_reveal_info(sr_commit_t *saved_commit, const sr_commit_t *commit)
sr_state_object_t
STATIC void reset_state_for_new_protocol_run(time_t valid_after)
STATIC void state_del_current_srv(void)
struct config_line_t * SharedRandValues
sr_commit_t * sr_state_get_commit(const char *rsa_fpr)
int sr_state_is_initialized(void)
void sr_state_free_all(void)
#define STATIC
Definition: testsupport.h:32
uint64_t n_protocol_runs
sr_phase_t
Definition: shared_random.h:54
STATIC time_t get_state_valid_until_time(time_t now)
sr_state_action_t
struct config_line_t * Commit
STATIC void new_protocol_run(time_t valid_after)
STATIC sr_phase_t get_sr_protocol_phase(time_t valid_after)
void sr_state_set_current_srv(const sr_srv_t *srv)
sr_srv_t * current_srv
sr_phase_t sr_state_get_phase(void)
const sr_srv_t * sr_state_get_current_srv(void)
void sr_state_clean_srvs(void)
void sr_state_set_valid_after(time_t valid_after)
unsigned int sr_state_srv_is_fresh(void)
unsigned int n_commit_rounds
sr_srv_t * previous_srv
const sr_srv_t * sr_state_get_previous_srv(void)
STATIC int is_phase_transition(sr_phase_t next_phase)
void sr_state_update(time_t valid_after)
digestmap_t * sr_state_get_commits(void)
STATIC const char * get_phase_str(sr_phase_t phase)
void sr_state_delete_commits(void)
unsigned int n_reveal_rounds
void sr_state_set_fresh_srv(void)
void sr_state_set_previous_srv(const sr_srv_t *srv)
This file contains ABI/API of the shared random protocol defined in proposal #250....
struct config_line_t * ExtraLines
unsigned int is_srv_fresh