1 /* Copyright (c) 2016-2021, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
5 * @file shared_random_state.h
6 * @brief Header for shared_random_state.c
9 #ifndef TOR_SHARED_RANDOM_STATE_H
10 #define TOR_SHARED_RANDOM_STATE_H
12 #include "feature/dirauth/shared_random.h"
14 /** Action that can be performed on the state for any objects. */
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,
23 /** Object in the state that can be queried through the state API. */
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. */
36 SR_STATE_OBJ_VALID_AFTER
,
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. */
44 /** Version of the protocol. */
46 /** The valid-after of the voting period we have prepared the state for. */
48 /** Until when is this state valid? */
50 /** Protocol phase. */
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
;
60 /** A map of all the received commitments for this protocol run. This is
61 * indexed by authority RSA identity digest. */
64 /** Current shared random value. */
65 sr_srv_t
*previous_srv
;
66 /** Previous shared random value. */
67 sr_srv_t
*current_srv
;
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.
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;
82 /** Persistent state of the protocol, as saved to disk. */
83 typedef struct sr_disk_state_t
{
85 /** Version of the protocol. */
87 /** Version of our running tor. */
89 /** Creation time of this state */
91 /** State valid until? */
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
;
103 /* Public methods: */
105 void sr_state_update(time_t valid_after
);
107 /* Private methods (only used by shared-random.c): */
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);
130 #ifdef SHARED_RANDOM_STATE_PRIVATE
132 STATIC
int disk_state_load_from_disk_impl(const char *fname
);
134 STATIC sr_phase_t
get_sr_protocol_phase(time_t valid_after
);
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
);
143 #endif /* defined(SHARED_RANDOM_STATE_PRIVATE) */
145 #ifdef TOR_UNIT_TESTS
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);
152 #endif /* defined(TOR_UNIT_TESTS) */
154 #endif /* !defined(TOR_SHARED_RANDOM_STATE_H) */