shared_random.h 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168
  1. /* Copyright (c) 2016, 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 \
  34. (((SR_COMMIT_LEN - 1) / 3) * 4 + 4)
  35. /* Length of base64 encoded reveal NOT including the NUL terminated byte.
  36. * Formula is taken from base64_encode_size. This adds up to 56 bytes. */
  37. #define SR_REVEAL_BASE64_LEN \
  38. (((SR_REVEAL_LEN - 1) / 3) * 4 + 4)
  39. /* Length of base64 encoded shared random value. It's 32 bytes long so 44
  40. * bytes from the base64_encode_size formula. That includes the '='
  41. * character at the end. */
  42. #define SR_SRV_VALUE_BASE64_LEN \
  43. (((DIGEST256_LEN - 1) / 3) * 4 + 4)
  44. /* Assert if commit valid flag is not set. */
  45. #define ASSERT_COMMIT_VALID(c) tor_assert((c)->valid)
  46. /* Protocol phase. */
  47. typedef enum {
  48. /* Commitment phase */
  49. SR_PHASE_COMMIT = 1,
  50. /* Reveal phase */
  51. SR_PHASE_REVEAL = 2,
  52. } sr_phase_t;
  53. /* A shared random value (SRV). */
  54. typedef struct sr_srv_t {
  55. /* The number of reveal values used to derive this SRV. */
  56. uint64_t num_reveals;
  57. /* The actual value. This is the stored result of SHA3-256. */
  58. uint8_t value[DIGEST256_LEN];
  59. } sr_srv_t;
  60. /* A commit (either ours or from another authority). */
  61. typedef struct sr_commit_t {
  62. /* Hashing algorithm used. */
  63. digest_algorithm_t alg;
  64. /* Indicate if this commit has been verified thus valid. */
  65. unsigned int valid:1;
  66. /* Commit owner info */
  67. /* The RSA identity key of the authority and its base16 representation,
  68. * which includes the NUL terminated byte. */
  69. char rsa_identity[DIGEST_LEN];
  70. char rsa_identity_hex[HEX_DIGEST_LEN + 1];
  71. /* Commitment information */
  72. /* Timestamp of reveal. Correspond to TIMESTAMP. */
  73. uint64_t reveal_ts;
  74. /* H(REVEAL) as found in COMMIT message. */
  75. char hashed_reveal[DIGEST256_LEN];
  76. /* Base64 encoded COMMIT. We use this to put it in our vote. */
  77. char encoded_commit[SR_COMMIT_BASE64_LEN + 1];
  78. /* Reveal information */
  79. /* H(RN) which is what we used as the random value for this commit. We
  80. * don't use the raw bytes since those are sent on the network thus
  81. * avoiding possible information leaks of our PRNG. */
  82. uint8_t random_number[SR_RANDOM_NUMBER_LEN];
  83. /* Timestamp of commit. Correspond to TIMESTAMP. */
  84. uint64_t commit_ts;
  85. /* This is the whole reveal message. We use it during verification */
  86. char encoded_reveal[SR_REVEAL_BASE64_LEN + 1];
  87. } sr_commit_t;
  88. /* API */
  89. /* Public methods: */
  90. int sr_init(int save_to_disk);
  91. void sr_save_and_cleanup(void);
  92. void sr_act_post_consensus(const networkstatus_t *consensus);
  93. void sr_handle_received_commits(smartlist_t *commits,
  94. crypto_pk_t *voter_key);
  95. sr_commit_t *sr_parse_commit(const smartlist_t *args);
  96. sr_srv_t *sr_parse_srv(const smartlist_t *args);
  97. char *sr_get_string_for_vote(void);
  98. char *sr_get_string_for_consensus(const smartlist_t *votes,
  99. int32_t num_srv_agreements);
  100. void sr_commit_free(sr_commit_t *commit);
  101. void sr_srv_encode(char *dst, size_t dst_len, const sr_srv_t *srv);
  102. /* Private methods (only used by shared_random_state.c): */
  103. static inline
  104. const char *sr_commit_get_rsa_fpr(const sr_commit_t *commit)
  105. {
  106. return commit->rsa_identity_hex;
  107. }
  108. void sr_compute_srv(void);
  109. sr_commit_t *sr_generate_our_commit(time_t timestamp,
  110. const authority_cert_t *my_rsa_cert);
  111. #ifdef SHARED_RANDOM_PRIVATE
  112. /* Encode */
  113. STATIC int reveal_encode(const sr_commit_t *commit, char *dst, size_t len);
  114. STATIC int commit_encode(const sr_commit_t *commit, char *dst, size_t len);
  115. /* Decode. */
  116. STATIC int commit_decode(const char *encoded, sr_commit_t *commit);
  117. STATIC int reveal_decode(const char *encoded, sr_commit_t *commit);
  118. STATIC int commit_has_reveal_value(const sr_commit_t *commit);
  119. STATIC int verify_commit_and_reveal(const sr_commit_t *commit);
  120. STATIC sr_srv_t *get_majority_srv_from_votes(const smartlist_t *votes,
  121. int current);
  122. STATIC void save_commit_to_state(sr_commit_t *commit);
  123. STATIC sr_srv_t *srv_dup(const sr_srv_t *orig);
  124. STATIC int commitments_are_the_same(const sr_commit_t *commit_one,
  125. const sr_commit_t *commit_two);
  126. STATIC int commit_is_authoritative(const sr_commit_t *commit,
  127. const char *voter_key);
  128. STATIC int should_keep_commit(const sr_commit_t *commit,
  129. const char *voter_key,
  130. sr_phase_t phase);
  131. STATIC void save_commit_during_reveal_phase(const sr_commit_t *commit);
  132. #endif /* SHARED_RANDOM_PRIVATE */
  133. #ifdef TOR_UNIT_TESTS
  134. void set_num_srv_agreements(int32_t value);
  135. #endif /* TOR_UNIT_TESTS */
  136. #endif /* TOR_SHARED_RANDOM_H */