Line data    Source code

       1             : /* Copyright (c) 2016-2021, The Tor Project, Inc. */
       2             : /* See LICENSE for licensing information */
       3             : 
       4             : #ifndef TOR_SHARED_RANDOM_H
       5             : #define TOR_SHARED_RANDOM_H
       6             : 
       7             : /**
       8             :  * \file shared_random.h
       9             :  *
      10             :  * \brief This file contains ABI/API of the shared random protocol defined in
      11             :  * proposal #250. Every public functions and data structure are namespaced
      12             :  * with "sr_" which stands for shared random.
      13             :  */
      14             : 
      15             : #include "core/or/or.h"
      16             : 
      17             : /** Protocol version */
      18             : #define SR_PROTO_VERSION  1
      19             : /** Default digest algorithm. */
      20             : #define SR_DIGEST_ALG DIGEST_SHA3_256
      21             : /** Invariant token in the SRV calculation. */
      22             : #define SR_SRV_TOKEN "shared-random"
      23             : /** Don't count the NUL terminated byte even though the TOKEN has it. */
      24             : #define SR_SRV_TOKEN_LEN (sizeof(SR_SRV_TOKEN) - 1)
      25             : 
      26             : /** Length of the random number (in bytes). */
      27             : #define SR_RANDOM_NUMBER_LEN 32
      28             : /** Size of a decoded commit value in a vote or state. It's a hash and a
      29             :  * timestamp. It adds up to 40 bytes. */
      30             : #define SR_COMMIT_LEN (sizeof(uint64_t) + DIGEST256_LEN)
      31             : /** Size of a decoded reveal value from a vote or state. It's a 64 bit
      32             :  * timestamp and the hashed random number. This adds up to 40 bytes. */
      33             : #define SR_REVEAL_LEN (sizeof(uint64_t) + DIGEST256_LEN)
      34             : /** Size of SRV message length. The construction is has follow:
      35             :  *  "shared-random" | INT_8(reveal_num) | INT_4(version) | PREV_SRV */
      36             : #define SR_SRV_MSG_LEN \
      37             :   (SR_SRV_TOKEN_LEN + sizeof(uint64_t) + sizeof(uint32_t) + DIGEST256_LEN)
      38             : 
      39             : /** Length of base64 encoded commit NOT including the NUL terminated byte.
      40             :  * Formula is taken from base64_encode_size. This adds up to 56 bytes. */
      41             : #define SR_COMMIT_BASE64_LEN (BASE64_LEN(SR_COMMIT_LEN))
      42             : /** Length of base64 encoded reveal NOT including the NUL terminated byte.
      43             :  * Formula is taken from base64_encode_size. This adds up to 56 bytes. */
      44             : #define SR_REVEAL_BASE64_LEN (BASE64_LEN(SR_REVEAL_LEN))
      45             : /** Length of base64 encoded shared random value. It's 32 bytes long so 44
      46             :  * bytes from the base64_encode_size formula. That includes the '='
      47             :  * character at the end. */
      48             : #define SR_SRV_VALUE_BASE64_LEN (BASE64_LEN(DIGEST256_LEN))
      49             : 
      50             : /** Assert if commit valid flag is not set. */
      51             : #define ASSERT_COMMIT_VALID(c) tor_assert((c)->valid)
      52             : 
      53             : /** Protocol phase. */
      54             : typedef enum {
      55             :   /** Commitment phase */
      56             :   SR_PHASE_COMMIT  = 1,
      57             :   /** Reveal phase */
      58             :   SR_PHASE_REVEAL  = 2,
      59             : } sr_phase_t;
      60             : 
      61             : /** A shared random value (SRV). */
      62             : typedef struct sr_srv_t {
      63             :   /** The number of reveal values used to derive this SRV. */
      64             :   uint64_t num_reveals;
      65             :   /** The actual value. This is the stored result of SHA3-256. */
      66             :   uint8_t value[DIGEST256_LEN];
      67             : } sr_srv_t;
      68             : 
      69             : /** A commit (either ours or from another authority). */
      70             : typedef struct sr_commit_t {
      71             :   /** Hashing algorithm used. */
      72             :   digest_algorithm_t alg;
      73             :   /** Indicate if this commit has been verified thus valid. */
      74             :   unsigned int valid:1;
      75             : 
      76             :   /* Commit owner info */
      77             : 
      78             :   /** The RSA identity key of the authority and its base16 representation,
      79             :    * which includes the NUL terminated byte. */
      80             :   char rsa_identity[DIGEST_LEN];
      81             :   char rsa_identity_hex[HEX_DIGEST_LEN + 1];
      82             : 
      83             :   /* Commitment information */
      84             : 
      85             :   /** Timestamp of reveal. Correspond to TIMESTAMP. */
      86             :   uint64_t reveal_ts;
      87             :   /* H(REVEAL) as found in COMMIT message. */
      88             :   char hashed_reveal[DIGEST256_LEN];
      89             :   /* Base64 encoded COMMIT. We use this to put it in our vote. */
      90             :   char encoded_commit[SR_COMMIT_BASE64_LEN + 1];
      91             : 
      92             :   /* Reveal information */
      93             : 
      94             :   /** H(RN) which is what we used as the random value for this commit. We
      95             :    * don't use the raw bytes since those are sent on the network thus
      96             :    * avoiding possible information leaks of our PRNG. */
      97             :   uint8_t random_number[SR_RANDOM_NUMBER_LEN];
      98             :   /** Timestamp of commit. Correspond to TIMESTAMP. */
      99             :   uint64_t commit_ts;
     100             :   /** This is the whole reveal message. We use it during verification */
     101             :   char encoded_reveal[SR_REVEAL_BASE64_LEN + 1];
     102             : } sr_commit_t;
     103             : 
     104             : /* API */
     105             : 
     106             : /* Public methods used _outside_ of the module.
     107             :  *
     108             :  * We need to nullify them if the module is disabled. */
     109             : #ifdef HAVE_MODULE_DIRAUTH
     110             : 
     111             : int sr_init(int save_to_disk);
     112             : void sr_save_and_cleanup(void);
     113             : void sr_act_post_consensus(const networkstatus_t *consensus);
     114             : 
     115             : #else /* !defined(HAVE_MODULE_DIRAUTH) */
     116             : 
     117             : static inline int
     118             : sr_init(int save_to_disk)
     119             : {
     120             :   (void) save_to_disk;
     121             :   /* Always return success. */
     122             :   return 0;
     123             : }
     124             : 
     125             : static inline void
     126             : sr_save_and_cleanup(void)
     127             : {
     128             : }
     129             : 
     130             : static inline void
     131             : sr_act_post_consensus(const networkstatus_t *consensus)
     132             : {
     133             :   (void) consensus;
     134             : }
     135             : 
     136             : #endif /* defined(HAVE_MODULE_DIRAUTH) */
     137             : 
     138             : /* Public methods used only by dirauth code. */
     139             : 
     140             : void sr_handle_received_commits(smartlist_t *commits,
     141             :                                 crypto_pk_t *voter_key);
     142             : sr_commit_t *sr_parse_commit(const smartlist_t *args);
     143             : char *sr_get_string_for_vote(void);
     144             : char *sr_get_string_for_consensus(const smartlist_t *votes,
     145             :                                   int32_t num_srv_agreements);
     146             : void sr_commit_free_(sr_commit_t *commit);
     147             : #define sr_commit_free(sr) FREE_AND_NULL(sr_commit_t, sr_commit_free_, (sr))
     148             : 
     149             : /* Private methods (only used by shared_random_state.c): */
     150             : static inline
     151        1397 : const char *sr_commit_get_rsa_fpr(const sr_commit_t *commit)
     152             : {
     153        1397 :   return commit->rsa_identity_hex;
     154             : }
     155             : 
     156             : void sr_compute_srv(void);
     157             : sr_commit_t *sr_generate_our_commit(time_t timestamp,
     158             :                                     const authority_cert_t *my_rsa_cert);
     159             : sr_srv_t *sr_srv_dup(const sr_srv_t *orig);
     160             : 
     161             : #ifdef SHARED_RANDOM_PRIVATE
     162             : 
     163             : /* Encode */
     164             : STATIC int reveal_encode(const sr_commit_t *commit, char *dst, size_t len);
     165             : STATIC int commit_encode(const sr_commit_t *commit, char *dst, size_t len);
     166             : /* Decode. */
     167             : STATIC int commit_decode(const char *encoded, sr_commit_t *commit);
     168             : STATIC int reveal_decode(const char *encoded, sr_commit_t *commit);
     169             : 
     170             : STATIC int commit_has_reveal_value(const sr_commit_t *commit);
     171             : 
     172             : STATIC int verify_commit_and_reveal(const sr_commit_t *commit);
     173             : 
     174             : STATIC sr_srv_t *get_majority_srv_from_votes(const smartlist_t *votes,
     175             :                                              int current);
     176             : 
     177             : STATIC void save_commit_to_state(sr_commit_t *commit);
     178             : STATIC int commitments_are_the_same(const sr_commit_t *commit_one,
     179             :                                     const sr_commit_t *commit_two);
     180             : STATIC int commit_is_authoritative(const sr_commit_t *commit,
     181             :                                    const char *voter_key);
     182             : STATIC int should_keep_commit(const sr_commit_t *commit,
     183             :                               const char *voter_key,
     184             :                               sr_phase_t phase);
     185             : STATIC void save_commit_during_reveal_phase(const sr_commit_t *commit);
     186             : 
     187             : #endif /* defined(SHARED_RANDOM_PRIVATE) */
     188             : 
     189             : #ifdef TOR_UNIT_TESTS
     190             : 
     191             : void set_num_srv_agreements(int32_t value);
     192             : 
     193             : #endif /* TOR_UNIT_TESTS */
     194             : 
     195             : #endif /* !defined(TOR_SHARED_RANDOM_H) */