Tor 0.4.9.0-alpha-dev
shared_random_state.h
Go to the documentation of this file.
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
13
14/** Action that can be performed on the state for any objects. */
15typedef 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. */
24typedef 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. */
41typedef 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. */
48 /** Until when is this state valid? */
50 /** Protocol phase. */
52
53 /** Number of runs completed. */
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;
81
82/** Persistent state of the protocol, as saved to disk. */
83typedef struct sr_disk_state_t {
84 uint32_t magic_;
85 /** Version of the protocol. */
87 /** Version of our running tor. */
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
105void sr_state_update(time_t valid_after);
106
107/* Private methods (only used by shared-random.c): */
108
109void sr_state_set_valid_after(time_t valid_after);
113void sr_state_set_previous_srv(const sr_srv_t *srv);
114void sr_state_set_current_srv(const sr_srv_t *srv);
115void sr_state_clean_srvs(void);
116digestmap_t *sr_state_get_commits(void);
117sr_commit_t *sr_state_get_commit(const char *rsa_fpr);
118void sr_state_add_commit(sr_commit_t *commit);
119void sr_state_delete_commits(void);
120void sr_state_copy_reveal_info(sr_commit_t *saved_commit,
121 const sr_commit_t *commit);
122unsigned int sr_state_srv_is_fresh(void);
123void sr_state_set_fresh_srv(void);
124void sr_state_unset_fresh_srv(void);
125int sr_state_init(int save_to_disk, int read_from_disk);
127void sr_state_save(void);
128void sr_state_free_all(void);
129
130#ifdef SHARED_RANDOM_STATE_PRIVATE
131
132STATIC int disk_state_load_from_disk_impl(const char *fname);
133
134STATIC sr_phase_t get_sr_protocol_phase(time_t valid_after);
135
136STATIC time_t get_state_valid_until_time(time_t now);
137STATIC const char *get_phase_str(sr_phase_t phase);
138STATIC void reset_state_for_new_protocol_run(time_t valid_after);
139STATIC void new_protocol_run(time_t valid_after);
140STATIC void state_rotate_srv(void);
142
143#endif /* defined(SHARED_RANDOM_STATE_PRIVATE) */
144
145#ifdef TOR_UNIT_TESTS
146
147STATIC void set_sr_phase(sr_phase_t phase);
148STATIC sr_state_t *get_sr_state(void);
151
152#endif /* defined(TOR_UNIT_TESTS) */
153
154#endif /* !defined(TOR_SHARED_RANDOM_STATE_H) */
This file contains ABI/API of the shared random protocol defined in proposal #250....
sr_phase_t
Definition: shared_random.h:54
STATIC sr_phase_t get_sr_protocol_phase(time_t valid_after)
STATIC int disk_state_load_from_disk_impl(const char *fname)
STATIC void reset_state_for_new_protocol_run(time_t valid_after)
STATIC void state_rotate_srv(void)
STATIC int is_phase_transition(sr_phase_t next_phase)
STATIC void state_del_previous_srv(void)
STATIC void new_protocol_run(time_t valid_after)
STATIC void state_del_current_srv(void)
STATIC const char * get_phase_str(sr_phase_t phase)
STATIC time_t get_state_valid_until_time(time_t now)
void sr_state_update(time_t valid_after)
void sr_state_set_fresh_srv(void)
void sr_state_save(void)
sr_state_object_t
@ SR_STATE_OBJ_CURSRV
@ SR_STATE_OBJ_PREVSRV
@ SR_STATE_OBJ_PHASE
@ SR_STATE_OBJ_VALID_AFTER
@ SR_STATE_OBJ_COMMITS
@ SR_STATE_OBJ_COMMIT
void sr_state_free_all(void)
void sr_state_copy_reveal_info(sr_commit_t *saved_commit, const sr_commit_t *commit)
void sr_state_set_previous_srv(const sr_srv_t *srv)
void sr_state_set_valid_after(time_t valid_after)
digestmap_t * sr_state_get_commits(void)
sr_state_action_t
void sr_state_clean_srvs(void)
void sr_state_set_current_srv(const sr_srv_t *srv)
int sr_state_init(int save_to_disk, int read_from_disk)
void sr_state_unset_fresh_srv(void)
void sr_state_delete_commits(void)
sr_commit_t * sr_state_get_commit(const char *rsa_fpr)
int sr_state_is_initialized(void)
const sr_srv_t * sr_state_get_previous_srv(void)
const sr_srv_t * sr_state_get_current_srv(void)
unsigned int sr_state_srv_is_fresh(void)
void sr_state_add_commit(sr_commit_t *commit)
sr_phase_t sr_state_get_phase(void)
struct config_line_t * Commit
struct config_line_t * SharedRandValues
struct config_line_t * ExtraLines
unsigned int n_reveal_rounds
uint64_t n_protocol_runs
unsigned int is_srv_fresh
sr_srv_t * previous_srv
digestmap_t * commits
sr_srv_t * current_srv
sr_phase_t phase
unsigned int n_commit_rounds
#define STATIC
Definition: testsupport.h:32