Tor  0.4.5.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) */
reset_state_for_new_protocol_run
STATIC void reset_state_for_new_protocol_run(time_t valid_after)
Definition: shared_random_state.c:749
sr_state_init
int sr_state_init(int save_to_disk, int read_from_disk)
Definition: shared_random_state.c:1293
sr_state_get_current_srv
const sr_srv_t * sr_state_get_current_srv(void)
Definition: shared_random_state.c:1075
sr_state_action_t
sr_state_action_t
Definition: shared_random_state.h:15
sr_state_object_t
sr_state_object_t
Definition: shared_random_state.h:24
sr_state_t::commits
digestmap_t * commits
Definition: shared_random_state.h:62
disk_state_load_from_disk_impl
STATIC int disk_state_load_from_disk_impl(const char *fname)
Definition: shared_random_state.c:642
state_del_current_srv
STATIC void state_del_current_srv(void)
Definition: shared_random_state.c:1006
sr_state_clean_srvs
void sr_state_clean_srvs(void)
Definition: shared_random_state.c:1094
sr_state_free_all
void sr_state_free_all(void)
Definition: shared_random_state.c:1258
sr_state_set_previous_srv
void sr_state_set_previous_srv(const sr_srv_t *srv)
Definition: shared_random_state.c:1065
sr_state_update
void sr_state_update(time_t valid_after)
Definition: shared_random_state.c:1115
sr_srv_t
Definition: shared_random.h:62
SR_STATE_OBJ_VALID_AFTER
@ SR_STATE_OBJ_VALID_AFTER
Definition: shared_random_state.h:36
get_state_valid_until_time
STATIC time_t get_state_valid_until_time(time_t now)
Definition: shared_random_state.c:136
sr_state_set_current_srv
void sr_state_set_current_srv(const sr_srv_t *srv)
Definition: shared_random_state.c:1086
sr_state_is_initialized
int sr_state_is_initialized(void)
Definition: shared_random_state.c:1279
sr_disk_state_t::ValidUntil
time_t ValidUntil
Definition: shared_random_state.h:92
sr_disk_state_t::Commit
struct config_line_t * Commit
Definition: shared_random_state.h:94
sr_state_t::n_protocol_runs
uint64_t n_protocol_runs
Definition: shared_random_state.h:54
sr_disk_state_t::TorVersion
char * TorVersion
Definition: shared_random_state.h:88
sr_state_t::version
uint32_t version
Definition: shared_random_state.h:45
sr_disk_state_t::SharedRandValues
struct config_line_t * SharedRandValues
Definition: shared_random_state.h:96
sr_state_save
void sr_state_save(void)
Definition: shared_random_state.c:1270
sr_disk_state_t::Version
int Version
Definition: shared_random_state.h:86
sr_state_unset_fresh_srv
void sr_state_unset_fresh_srv(void)
Definition: shared_random_state.c:1244
sr_disk_state_t
Definition: shared_random_state.h:83
sr_state_t::phase
sr_phase_t phase
Definition: shared_random_state.h:51
sr_state_t::fname
char * fname
Definition: shared_random_state.h:43
sr_state_copy_reveal_info
void sr_state_copy_reveal_info(sr_commit_t *saved_commit, const sr_commit_t *commit)
Definition: shared_random_state.c:1216
sr_disk_state_t::ExtraLines
struct config_line_t * ExtraLines
Definition: shared_random_state.h:98
sr_state_t::current_srv
sr_srv_t * current_srv
Definition: shared_random_state.h:67
shared_random.h
This file contains ABI/API of the shared random protocol defined in proposal #250....
sr_state_t::valid_until
time_t valid_until
Definition: shared_random_state.h:49
sr_state_set_fresh_srv
void sr_state_set_fresh_srv(void)
Definition: shared_random_state.c:1236
sr_commit_t
Definition: shared_random.h:70
SR_STATE_OBJ_PHASE
@ SR_STATE_OBJ_PHASE
Definition: shared_random_state.h:34
sr_state_t::n_reveal_rounds
unsigned int n_reveal_rounds
Definition: shared_random_state.h:58
sr_state_t::previous_srv
sr_srv_t * previous_srv
Definition: shared_random_state.h:65
sr_disk_state_t::ValidAfter
time_t ValidAfter
Definition: shared_random_state.h:90
sr_state_t
Definition: shared_random_state.h:41
sr_state_get_commits
digestmap_t * sr_state_get_commits(void)
Definition: shared_random_state.c:1103
sr_state_t::valid_after
time_t valid_after
Definition: shared_random_state.h:47
state_del_previous_srv
STATIC void state_del_previous_srv(void)
Definition: shared_random_state.c:1014
sr_state_srv_is_fresh
unsigned int sr_state_srv_is_fresh(void)
Definition: shared_random_state.c:1251
sr_state_t::is_srv_fresh
unsigned int is_srv_fresh
Definition: shared_random_state.h:79
sr_state_add_commit
void sr_state_add_commit(sr_commit_t *commit)
Definition: shared_random_state.c:1193
sr_state_get_commit
sr_commit_t * sr_state_get_commit(const char *rsa_fpr)
Definition: shared_random_state.c:1179
is_phase_transition
STATIC int is_phase_transition(sr_phase_t next_phase)
Definition: shared_random_state.c:804
get_phase_str
STATIC const char * get_phase_str(sr_phase_t phase)
Definition: shared_random_state.c:117
new_protocol_run
STATIC void new_protocol_run(time_t valid_after)
Definition: shared_random_state.c:770
SR_STATE_OBJ_COMMIT
@ SR_STATE_OBJ_COMMIT
Definition: shared_random_state.h:26
config_line_t
Definition: confline.h:29
sr_state_get_phase
sr_phase_t sr_state_get_phase(void)
Definition: shared_random_state.c:1042
sr_state_delete_commits
void sr_state_delete_commits(void)
Definition: shared_random_state.c:1207
state_rotate_srv
STATIC void state_rotate_srv(void)
Definition: shared_random_state.c:1022
SR_STATE_OBJ_COMMITS
@ SR_STATE_OBJ_COMMITS
Definition: shared_random_state.h:28
STATIC
#define STATIC
Definition: testsupport.h:32
SR_STATE_OBJ_CURSRV
@ SR_STATE_OBJ_CURSRV
Definition: shared_random_state.h:30
sr_state_set_valid_after
void sr_state_set_valid_after(time_t valid_after)
Definition: shared_random_state.c:1034
sr_state_t::n_commit_rounds
unsigned int n_commit_rounds
Definition: shared_random_state.h:56
sr_state_get_previous_srv
const sr_srv_t * sr_state_get_previous_srv(void)
Definition: shared_random_state.c:1054
get_sr_protocol_phase
STATIC sr_phase_t get_sr_protocol_phase(time_t valid_after)
Definition: shared_random_state.c:167
SR_STATE_OBJ_PREVSRV
@ SR_STATE_OBJ_PREVSRV
Definition: shared_random_state.h:32
sr_phase_t
sr_phase_t
Definition: shared_random.h:54