shared_random.h 6.3 KB

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