This file contains ABI/API of the shared random protocol defined in proposal #250. Every public functions and data structure are namespaced with "sr_" which stands for shared random. More...

#include "core/or/or.h"

Data Structures
struct	sr_srv_t

struct	sr_commit_t

Macros
#define	SR_PROTO_VERSION 1

#define	SR_DIGEST_ALG DIGEST_SHA3_256

#define	SR_SRV_TOKEN "shared-random"

#define	SR_SRV_TOKEN_LEN (sizeof(SR_SRV_TOKEN) - 1)

#define	SR_RANDOM_NUMBER_LEN 32

#define	SR_COMMIT_LEN (sizeof(uint64_t) + DIGEST256_LEN)

#define	SR_REVEAL_LEN (sizeof(uint64_t) + DIGEST256_LEN)

#define	SR_SRV_MSG_LEN (SR_SRV_TOKEN_LEN + sizeof(uint64_t) + sizeof(uint32_t) + DIGEST256_LEN)

#define	SR_COMMIT_BASE64_LEN (BASE64_LEN(SR_COMMIT_LEN))

#define	SR_REVEAL_BASE64_LEN (BASE64_LEN(SR_REVEAL_LEN))

#define	SR_SRV_VALUE_BASE64_LEN (BASE64_LEN(DIGEST256_LEN))

#define	ASSERT_COMMIT_VALID(c) tor_assert((c)->valid)

#define	sr_commit_free(sr) FREE_AND_NULL(sr_commit_t, sr_commit_free_, (sr))

Enumerations
enum	sr_phase_t { SR_PHASE_COMMIT = 1 , SR_PHASE_REVEAL = 2 }

Functions
static int	sr_init (int save_to_disk)

static void	sr_save_and_cleanup (void)

static void	sr_act_post_consensus (const networkstatus_t *consensus)

void	sr_handle_received_commits (smartlist_t commits, crypto_pk_t voter_key)

sr_commit_t *	sr_parse_commit (const smartlist_t *args)

char *	sr_get_string_for_vote (void)

char *	sr_get_string_for_consensus (const smartlist_t *votes, int32_t num_srv_agreements)

void	sr_commit_free_ (sr_commit_t *commit)

static const char *	sr_commit_get_rsa_fpr (const sr_commit_t *commit)

void	sr_compute_srv (void)

sr_commit_t *	sr_generate_our_commit (time_t timestamp, const authority_cert_t *my_rsa_cert)

sr_srv_t *	sr_srv_dup (const sr_srv_t *orig)

Detailed Description

This file contains ABI/API of the shared random protocol defined in proposal #250. Every public functions and data structure are namespaced with "sr_" which stands for shared random.

Definition in file shared_random.h.

Macro Definition Documentation

◆ ASSERT_COMMIT_VALID

#define ASSERT_COMMIT_VALID ( c ) tor_assert((c)->valid)

Assert if commit valid flag is not set.

Definition at line 51 of file shared_random.h.

◆ SR_COMMIT_BASE64_LEN

#define SR_COMMIT_BASE64_LEN (BASE64_LEN(SR_COMMIT_LEN))

Length of base64 encoded commit NOT including the NUL terminated byte. Formula is taken from base64_encode_size. This adds up to 56 bytes.

Definition at line 41 of file shared_random.h.

◆ SR_COMMIT_LEN

#define SR_COMMIT_LEN (sizeof(uint64_t) + DIGEST256_LEN)

Size of a decoded commit value in a vote or state. It's a hash and a timestamp. It adds up to 40 bytes.

Definition at line 30 of file shared_random.h.

◆ SR_DIGEST_ALG

#define SR_DIGEST_ALG DIGEST_SHA3_256

Default digest algorithm.

Definition at line 20 of file shared_random.h.

◆ SR_PROTO_VERSION

#define SR_PROTO_VERSION 1

Protocol version

Definition at line 18 of file shared_random.h.

◆ SR_RANDOM_NUMBER_LEN

#define SR_RANDOM_NUMBER_LEN 32

Length of the random number (in bytes).

Definition at line 27 of file shared_random.h.

◆ SR_REVEAL_BASE64_LEN

#define SR_REVEAL_BASE64_LEN (BASE64_LEN(SR_REVEAL_LEN))

Length of base64 encoded reveal NOT including the NUL terminated byte. Formula is taken from base64_encode_size. This adds up to 56 bytes.

Definition at line 44 of file shared_random.h.

◆ SR_REVEAL_LEN

#define SR_REVEAL_LEN (sizeof(uint64_t) + DIGEST256_LEN)

Size of a decoded reveal value from a vote or state. It's a 64 bit timestamp and the hashed random number. This adds up to 40 bytes.

Definition at line 33 of file shared_random.h.

◆ SR_SRV_MSG_LEN

#define SR_SRV_MSG_LEN (SR_SRV_TOKEN_LEN + sizeof(uint64_t) + sizeof(uint32_t) + DIGEST256_LEN)

Size of SRV message length. The construction is has follow: "shared-random" | INT_8(reveal_num) | INT_4(version) | PREV_SRV

Definition at line 36 of file shared_random.h.

◆ SR_SRV_TOKEN

#define SR_SRV_TOKEN "shared-random"

Invariant token in the SRV calculation.

Definition at line 22 of file shared_random.h.

◆ SR_SRV_TOKEN_LEN

#define SR_SRV_TOKEN_LEN (sizeof(SR_SRV_TOKEN) - 1)

Don't count the NUL terminated byte even though the TOKEN has it.

Definition at line 24 of file shared_random.h.

◆ SR_SRV_VALUE_BASE64_LEN

#define SR_SRV_VALUE_BASE64_LEN (BASE64_LEN(DIGEST256_LEN))

Length of base64 encoded shared random value. It's 32 bytes long so 44 bytes from the base64_encode_size formula. That includes the '=' character at the end.

Definition at line 48 of file shared_random.h.

Enumeration Type Documentation

◆ sr_phase_t

enum sr_phase_t

Protocol phase.

Enumerator
SR_PHASE_COMMIT	Commitment phase
SR_PHASE_REVEAL	Reveal phase

Definition at line 54 of file shared_random.h.

Function Documentation

◆ sr_commit_free_()

void sr_commit_free_ ( sr_commit_t * commit )

Free a commit object.

Definition at line 875 of file shared_random.c.

Referenced by commit_free_().

◆ sr_compute_srv()

void sr_compute_srv ( void )

Compute the shared random value based on the active commits in our state.

Definition at line 945 of file shared_random.c.

Referenced by new_protocol_run().

◆ sr_generate_our_commit()

sr_commit_t* sr_generate_our_commit	(	time_t	timestamp,
		const authority_cert_t *	my_rsa_cert
	)

Generate the commitment/reveal value for the protocol run starting at timestamp. my_rsa_cert is our authority RSA certificate.

Definition at line 888 of file shared_random.c.

◆ sr_get_string_for_consensus()

char* sr_get_string_for_consensus	(	const smartlist_t *	votes,
		int32_t	num_srv_agreements
	)

Return a heap-allocated string that should be put in the consensus and contains the shared randomness values. It's the responsibility of the caller to free the string. NULL is returned if no SRV(s) available.

This is called when a consensus (any flavor) is bring created thus it should NEVER change the state nor the state should be changed in between consensus creation.

num_srv_agreements is taken from the votes thus the voted value that should be used.

Definition at line 1196 of file shared_random.c.

◆ sr_get_string_for_vote()

char* sr_get_string_for_vote ( void )

Return a heap-allocated string containing commits that should be put in the votes. It's the responsibility of the caller to free the string. This always return a valid string, either empty or with line(s).

Definition at line 1130 of file shared_random.c.

◆ sr_handle_received_commits()

void sr_handle_received_commits	(	smartlist_t *	commits,
		crypto_pk_t *	voter_key
	)

Called when we are done parsing a vote by voter_key that might contain some useful commits. Find if any of them should be kept and update our state accordingly. Once done, the list of commitments will be empty.

Definition at line 1093 of file shared_random.c.

◆ sr_parse_commit()

sr_commit_t* sr_parse_commit ( const smartlist_t * args )

Parse a commit from a vote or from our disk state and return a newly allocated commit object. NULL is returned on error.

The commit's data is in args and the order matters very much: version, algname, RSA fingerprint, commit value[, reveal value]

Definition at line 1023 of file shared_random.c.

◆ sr_srv_dup()

sr_srv_t* sr_srv_dup ( const sr_srv_t * orig )

Return a heap allocated copy of the SRV orig.

Definition at line 126 of file shared_random.c.

Referenced by state_rotate_srv().

Data Structures

Macros

Enumerations

Functions