hs_descriptor.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284
  1. /* Copyright (c) 2016-2017, The Tor Project, Inc. */
  2. /* See LICENSE for licensing information */
  3. /**
  4. * \file hs_descriptor.h
  5. * \brief Header file for hs_descriptor.c
  6. **/
  7. #ifndef TOR_HS_DESCRIPTOR_H
  8. #define TOR_HS_DESCRIPTOR_H
  9. #include <stdint.h>
  10. #include "or.h"
  11. #include "address.h"
  12. #include "container.h"
  13. #include "crypto.h"
  14. #include "crypto_ed25519.h"
  15. #include "torcert.h"
  16. /* Trunnel */
  17. struct link_specifier_t;
  18. /* The earliest descriptor format version we support. */
  19. #define HS_DESC_SUPPORTED_FORMAT_VERSION_MIN 3
  20. /* The latest descriptor format version we support. */
  21. #define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX 3
  22. /* Default lifetime of a descriptor in seconds. The valus is set at 3 hours
  23. * which is 180 minutes or 10800 seconds. */
  24. #define HS_DESC_DEFAULT_LIFETIME (3 * 60 * 60)
  25. /* Maximum lifetime of a descriptor in seconds. The value is set at 12 hours
  26. * which is 720 minutes or 43200 seconds. */
  27. #define HS_DESC_MAX_LIFETIME (12 * 60 * 60)
  28. /* Lifetime of certificate in the descriptor. This defines the lifetime of the
  29. * descriptor signing key and the cross certification cert of that key. It is
  30. * set to 54 hours because a descriptor can be around for 48 hours and because
  31. * consensuses are used after the hour, add an extra 6 hours to give some time
  32. * for the service to stop using it. */
  33. #define HS_DESC_CERT_LIFETIME (54 * 60 * 60)
  34. /* Length of the salt needed for the encrypted section of a descriptor. */
  35. #define HS_DESC_ENCRYPTED_SALT_LEN 16
  36. /* Length of the secret input needed for the KDF construction which derives
  37. * the encryption key for the encrypted data section of the descriptor. This
  38. * adds up to 68 bytes being the blinded key, hashed subcredential and
  39. * revision counter. */
  40. #define HS_DESC_ENCRYPTED_SECRET_INPUT_LEN \
  41. ED25519_PUBKEY_LEN + DIGEST256_LEN + sizeof(uint64_t)
  42. /* Length of the KDF output value which is the length of the secret key,
  43. * the secret IV and MAC key length which is the length of H() output. */
  44. #define HS_DESC_ENCRYPTED_KDF_OUTPUT_LEN \
  45. CIPHER256_KEY_LEN + CIPHER_IV_LEN + DIGEST256_LEN
  46. /* Pad plaintext of superencrypted data section before encryption so that its
  47. * length is a multiple of this value. */
  48. #define HS_DESC_SUPERENC_PLAINTEXT_PAD_MULTIPLE 10000
  49. /* Maximum length in bytes of a full hidden service descriptor. */
  50. #define HS_DESC_MAX_LEN 50000 /* 50kb max size */
  51. /* Key length for the descriptor symmetric encryption. As specified in the
  52. * protocol, we use AES-256 for the encrypted section of the descriptor. The
  53. * following is the length in bytes and the bit size. */
  54. #define HS_DESC_ENCRYPTED_KEY_LEN CIPHER256_KEY_LEN
  55. #define HS_DESC_ENCRYPTED_BIT_SIZE (HS_DESC_ENCRYPTED_KEY_LEN * 8)
  56. /* Type of authentication in the descriptor. */
  57. typedef enum {
  58. HS_DESC_AUTH_ED25519 = 1
  59. } hs_desc_auth_type_t;
  60. /* Link specifier object that contains information on how to extend to the
  61. * relay that is the address, port and handshake type. */
  62. typedef struct hs_desc_link_specifier_t {
  63. /* Indicate the type of link specifier. See trunnel ed25519_cert
  64. * specification. */
  65. uint8_t type;
  66. /* It must be one of these types, can't be more than one. */
  67. union {
  68. /* IP address and port of the relay use to extend. */
  69. tor_addr_port_t ap;
  70. /* Legacy identity. A 20-byte SHA1 identity fingerprint. */
  71. uint8_t legacy_id[DIGEST_LEN];
  72. /* ed25519 identity. A 32-byte key. */
  73. uint8_t ed25519_id[ED25519_PUBKEY_LEN];
  74. } u;
  75. } hs_desc_link_specifier_t;
  76. /* Introduction point information located in a descriptor. */
  77. typedef struct hs_desc_intro_point_t {
  78. /* Link specifier(s) which details how to extend to the relay. This list
  79. * contains hs_desc_link_specifier_t object. It MUST have at least one. */
  80. smartlist_t *link_specifiers;
  81. /* Onion key of the introduction point used to extend to it for the ntor
  82. * handshake. */
  83. curve25519_public_key_t onion_key;
  84. /* Authentication key used to establish the introduction point circuit and
  85. * cross-certifies the blinded public key for the replica thus signed by
  86. * the blinded key and in turn signs it. */
  87. tor_cert_t *auth_key_cert;
  88. /* Encryption key for the "ntor" type. */
  89. curve25519_public_key_t enc_key;
  90. /* Certificate cross certifying the descriptor signing key by the encryption
  91. * curve25519 key. This certificate contains the signing key and is of type
  92. * CERT_TYPE_CROSS_HS_IP_KEYS [0B]. */
  93. tor_cert_t *enc_key_cert;
  94. /* (Optional): If this introduction point is a legacy one that is version <=
  95. * 0.2.9.x (HSIntro=3), we use this extra key for the intro point to be able
  96. * to relay the cells to the service correctly. */
  97. struct {
  98. /* RSA public key. */
  99. crypto_pk_t *key;
  100. /* Cross certified cert with the descriptor signing key (RSA->Ed). Because
  101. * of the cross certification API, we need to keep the certificate binary
  102. * blob and its length in order to properly encode it after. */
  103. struct {
  104. uint8_t *encoded;
  105. size_t len;
  106. } cert;
  107. } legacy;
  108. /* True iff the introduction point has passed the cross certification. Upon
  109. * decoding an intro point, this must be true. */
  110. unsigned int cross_certified : 1;
  111. } hs_desc_intro_point_t;
  112. /* The encrypted data section of a descriptor. Obviously the data in this is
  113. * in plaintext but encrypted once encoded. */
  114. typedef struct hs_desc_encrypted_data_t {
  115. /* Bitfield of CREATE2 cell supported formats. The only currently supported
  116. * format is ntor. */
  117. unsigned int create2_ntor : 1;
  118. /* A list of authentication types that a client must at least support one
  119. * in order to contact the service. Contains NULL terminated strings. */
  120. smartlist_t *intro_auth_types;
  121. /* Is this descriptor a single onion service? */
  122. unsigned int single_onion_service : 1;
  123. /* A list of intro points. Contains hs_desc_intro_point_t objects. */
  124. smartlist_t *intro_points;
  125. } hs_desc_encrypted_data_t;
  126. /* Plaintext data that is unencrypted information of the descriptor. */
  127. typedef struct hs_desc_plaintext_data_t {
  128. /* Version of the descriptor format. Spec specifies this field as a
  129. * positive integer. */
  130. uint32_t version;
  131. /* The lifetime of the descriptor in seconds. */
  132. uint32_t lifetime_sec;
  133. /* Certificate with the short-term ed22519 descriptor signing key for the
  134. * replica which is signed by the blinded public key for that replica. */
  135. tor_cert_t *signing_key_cert;
  136. /* Signing public key which is used to sign the descriptor. Same public key
  137. * as in the signing key certificate. */
  138. ed25519_public_key_t signing_pubkey;
  139. /* Blinded public key used for this descriptor derived from the master
  140. * identity key and generated for a specific replica number. */
  141. ed25519_public_key_t blinded_pubkey;
  142. /* Revision counter is incremented at each upload, regardless of whether
  143. * the descriptor has changed. This avoids leaking whether the descriptor
  144. * has changed. Spec specifies this as a 8 bytes positive integer. */
  145. uint64_t revision_counter;
  146. /* Decoding only: The b64-decoded superencrypted blob from the descriptor */
  147. uint8_t *superencrypted_blob;
  148. /* Decoding only: Size of the superencrypted_blob */
  149. size_t superencrypted_blob_size;
  150. } hs_desc_plaintext_data_t;
  151. /* Service descriptor in its decoded form. */
  152. typedef struct hs_descriptor_t {
  153. /* Contains the plaintext part of the descriptor. */
  154. hs_desc_plaintext_data_t plaintext_data;
  155. /* The following contains what's in the encrypted part of the descriptor.
  156. * It's only encrypted in the encoded version of the descriptor thus the
  157. * data contained in that object is in plaintext. */
  158. hs_desc_encrypted_data_t encrypted_data;
  159. /* Subcredentials of a service, used by the client and service to decrypt
  160. * the encrypted data. */
  161. uint8_t subcredential[DIGEST256_LEN];
  162. } hs_descriptor_t;
  163. /* Return true iff the given descriptor format version is supported. */
  164. static inline int
  165. hs_desc_is_supported_version(uint32_t version)
  166. {
  167. if (version < HS_DESC_SUPPORTED_FORMAT_VERSION_MIN ||
  168. version > HS_DESC_SUPPORTED_FORMAT_VERSION_MAX) {
  169. return 0;
  170. }
  171. return 1;
  172. }
  173. /* Public API. */
  174. void hs_descriptor_free_(hs_descriptor_t *desc);
  175. #define hs_descriptor_free(desc) \
  176. FREE_AND_NULL(hs_descriptor_t, hs_descriptor_free_, (desc))
  177. void hs_desc_plaintext_data_free_(hs_desc_plaintext_data_t *desc);
  178. #define hs_desc_plaintext_data_free(desc) \
  179. FREE_AND_NULL(hs_desc_plaintext_data_t, hs_desc_plaintext_data_free_, (desc))
  180. void hs_desc_encrypted_data_free_(hs_desc_encrypted_data_t *desc);
  181. #define hs_desc_encrypted_data_free(desc) \
  182. FREE_AND_NULL(hs_desc_encrypted_data_t, hs_desc_encrypted_data_free_, (desc))
  183. void hs_desc_link_specifier_free_(hs_desc_link_specifier_t *ls);
  184. #define hs_desc_link_specifier_free(ls) \
  185. FREE_AND_NULL(hs_desc_link_specifier_t, hs_desc_link_specifier_free_, (ls))
  186. hs_desc_link_specifier_t *hs_desc_link_specifier_new(
  187. const extend_info_t *info, uint8_t type);
  188. void hs_descriptor_clear_intro_points(hs_descriptor_t *desc);
  189. MOCK_DECL(int,
  190. hs_desc_encode_descriptor,(const hs_descriptor_t *desc,
  191. const ed25519_keypair_t *signing_kp,
  192. char **encoded_out));
  193. int hs_desc_decode_descriptor(const char *encoded,
  194. const uint8_t *subcredential,
  195. hs_descriptor_t **desc_out);
  196. int hs_desc_decode_plaintext(const char *encoded,
  197. hs_desc_plaintext_data_t *plaintext);
  198. int hs_desc_decode_encrypted(const hs_descriptor_t *desc,
  199. hs_desc_encrypted_data_t *desc_out);
  200. size_t hs_desc_obj_size(const hs_descriptor_t *data);
  201. size_t hs_desc_plaintext_obj_size(const hs_desc_plaintext_data_t *data);
  202. hs_desc_intro_point_t *hs_desc_intro_point_new(void);
  203. void hs_desc_intro_point_free_(hs_desc_intro_point_t *ip);
  204. #define hs_desc_intro_point_free(ip) \
  205. FREE_AND_NULL(hs_desc_intro_point_t, hs_desc_intro_point_free_, (ip))
  206. link_specifier_t *hs_desc_lspec_to_trunnel(
  207. const hs_desc_link_specifier_t *spec);
  208. #ifdef HS_DESCRIPTOR_PRIVATE
  209. /* Encoding. */
  210. STATIC char *encode_link_specifiers(const smartlist_t *specs);
  211. STATIC size_t build_plaintext_padding(const char *plaintext,
  212. size_t plaintext_len,
  213. uint8_t **padded_out);
  214. /* Decoding. */
  215. STATIC smartlist_t *decode_link_specifiers(const char *encoded);
  216. STATIC hs_desc_intro_point_t *decode_introduction_point(
  217. const hs_descriptor_t *desc,
  218. const char *text);
  219. STATIC int encrypted_data_length_is_valid(size_t len);
  220. STATIC int cert_is_valid(tor_cert_t *cert, uint8_t type,
  221. const char *log_obj_type);
  222. STATIC int desc_sig_is_valid(const char *b64_sig,
  223. const ed25519_public_key_t *signing_pubkey,
  224. const char *encoded_desc, size_t encoded_len);
  225. STATIC size_t decode_superencrypted(const char *message, size_t message_len,
  226. uint8_t **encrypted_out);
  227. STATIC void desc_plaintext_data_free_contents(hs_desc_plaintext_data_t *desc);
  228. MOCK_DECL(STATIC size_t, decrypt_desc_layer,(const hs_descriptor_t *desc,
  229. const uint8_t *encrypted_blob,
  230. size_t encrypted_blob_size,
  231. int is_superencrypted_layer,
  232. char **decrypted_out));
  233. #endif /* defined(HS_DESCRIPTOR_PRIVATE) */
  234. #endif /* !defined(TOR_HS_DESCRIPTOR_H) */