Tor  0.4.4.0-alpha-dev
Data Structures | Macros | Enumerations | Functions
shared_random.h File Reference

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"

Go to the source code of this file.

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_tsr_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_tsr_generate_our_commit (time_t timestamp, const authority_cert_t *my_rsa_cert)
 
sr_srv_tsr_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().