hs_descriptor.h (16011B)
1 /* Copyright (c) 2016-2021, The Tor Project, Inc. */ 2 /* See LICENSE for licensing information */ 3 4 /** 5 * \file hs_descriptor.h 6 * \brief Header file for hs_descriptor.c 7 **/ 8 9 #ifndef TOR_HS_DESCRIPTOR_H 10 #define TOR_HS_DESCRIPTOR_H 11 12 #include <stdint.h> 13 14 #include "core/or/or.h" 15 #include "trunnel/ed25519_cert.h" /* needed for trunnel */ 16 #include "feature/nodelist/torcert.h" 17 #include "core/crypto/hs_ntor.h" /* for hs_subcredential_t */ 18 #include "feature/hs/hs_pow.h" 19 20 /* Trunnel */ 21 struct link_specifier_t; 22 23 /** The earliest descriptor format version we support. */ 24 #define HS_DESC_SUPPORTED_FORMAT_VERSION_MIN 3 25 /** The latest descriptor format version we support. */ 26 #define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX 3 27 28 /** Default lifetime of a descriptor in seconds. The valus is set at 3 hours 29 * which is 180 minutes or 10800 seconds. */ 30 #define HS_DESC_DEFAULT_LIFETIME (3 * 60 * 60) 31 /** Maximum lifetime of a descriptor in seconds. The value is set at 12 hours 32 * which is 720 minutes or 43200 seconds. */ 33 #define HS_DESC_MAX_LIFETIME (12 * 60 * 60) 34 /** Lifetime of certificate in the descriptor. This defines the lifetime of the 35 * descriptor signing key and the cross certification cert of that key. It is 36 * set to 54 hours because a descriptor can be around for 48 hours and because 37 * consensuses are used after the hour, add an extra 6 hours to give some time 38 * for the service to stop using it. */ 39 #define HS_DESC_CERT_LIFETIME (54 * 60 * 60) 40 /** Length of the salt needed for the encrypted section of a descriptor. */ 41 #define HS_DESC_ENCRYPTED_SALT_LEN 16 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 52 /** Key length for the descriptor symmetric encryption. As specified in the 53 * protocol, we use AES-256 for the encrypted section of the descriptor. The 54 * following is the length in bytes and the bit size. */ 55 #define HS_DESC_ENCRYPTED_KEY_LEN CIPHER256_KEY_LEN 56 #define HS_DESC_ENCRYPTED_BIT_SIZE (HS_DESC_ENCRYPTED_KEY_LEN * 8) 57 58 /** Length of each components in the auth client section in the descriptor. */ 59 #define HS_DESC_CLIENT_ID_LEN 8 60 #define HS_DESC_DESCRIPTOR_COOKIE_LEN 16 61 #define HS_DESC_COOKIE_KEY_LEN 32 62 #define HS_DESC_COOKIE_KEY_BIT_SIZE (HS_DESC_COOKIE_KEY_LEN * 8) 63 #define HS_DESC_ENCRYPED_COOKIE_LEN HS_DESC_DESCRIPTOR_COOKIE_LEN 64 65 /** The number of auth client entries in the descriptor must be the multiple 66 * of this constant. */ 67 #define HS_DESC_AUTH_CLIENT_MULTIPLE 16 68 69 /** Type of authentication in the descriptor. */ 70 typedef enum { 71 HS_DESC_AUTH_ED25519 = 1 72 } hs_desc_auth_type_t; 73 74 /** Error code when decoding a descriptor. */ 75 typedef enum { 76 /* The configured client authorization for the requested .onion address 77 * failed to decode the descriptor. */ 78 HS_DESC_DECODE_BAD_CLIENT_AUTH = -6, 79 80 /* The requested .onion address requires a client authorization. */ 81 HS_DESC_DECODE_NEED_CLIENT_AUTH = -5, 82 83 /* Error during decryption of the encrypted layer. */ 84 HS_DESC_DECODE_ENCRYPTED_ERROR = -4, 85 86 /* Error during decryption of the super encrypted layer. */ 87 HS_DESC_DECODE_SUPERENC_ERROR = -3, 88 89 /* Error while decoding the plaintext section. */ 90 HS_DESC_DECODE_PLAINTEXT_ERROR = -2, 91 92 /* Generic error. */ 93 HS_DESC_DECODE_GENERIC_ERROR = -1, 94 95 /* Decoding a descriptor was successful. */ 96 HS_DESC_DECODE_OK = 0, 97 } hs_desc_decode_status_t; 98 99 /** Introduction point information located in a descriptor. */ 100 typedef struct hs_desc_intro_point_t { 101 /** Link specifier(s) which details how to extend to the relay. This list 102 * contains link_specifier_t objects. It MUST have at least one. */ 103 smartlist_t *link_specifiers; 104 105 /** Onion key of the introduction point used to extend to it for the ntor 106 * handshake. */ 107 curve25519_public_key_t onion_key; 108 109 /** Authentication key used to establish the introduction point circuit and 110 * cross-certifies the blinded public key for the replica thus signed by 111 * the blinded key and in turn signs it. */ 112 tor_cert_t *auth_key_cert; 113 114 /** Encryption key for the "ntor" type. */ 115 curve25519_public_key_t enc_key; 116 117 /** Certificate cross certifying the descriptor signing key by the encryption 118 * curve25519 key. This certificate contains the signing key and is of type 119 * CERT_TYPE_CROSS_HS_IP_KEYS [0B]. */ 120 tor_cert_t *enc_key_cert; 121 122 /** (Optional): If this introduction point is a legacy one that is version <= 123 * 0.2.9.x (HSIntro=3), we use this extra key for the intro point to be able 124 * to relay the cells to the service correctly. */ 125 struct { 126 /** RSA public key. */ 127 crypto_pk_t *key; 128 129 /** Cross certified cert with the descriptor signing key (RSA->Ed). Because 130 * of the cross certification API, we need to keep the certificate binary 131 * blob and its length in order to properly encode it after. */ 132 struct { 133 uint8_t *encoded; 134 size_t len; 135 } cert; 136 } legacy; 137 138 /** True iff the introduction point has passed the cross certification. Upon 139 * decoding an intro point, this must be true. */ 140 unsigned int cross_certified : 1; 141 } hs_desc_intro_point_t; 142 143 /** Authorized client information located in a descriptor. */ 144 typedef struct hs_desc_authorized_client_t { 145 /** An identifier that the client will use to identify which auth client 146 * entry it needs to use. */ 147 uint8_t client_id[HS_DESC_CLIENT_ID_LEN]; 148 149 /** An IV that is used to decrypt the encrypted descriptor cookie. */ 150 uint8_t iv[CIPHER_IV_LEN]; 151 152 /** An encrypted descriptor cookie that the client needs to decrypt to use 153 * it to decrypt the descriptor. */ 154 uint8_t encrypted_cookie[HS_DESC_ENCRYPED_COOKIE_LEN]; 155 } hs_desc_authorized_client_t; 156 157 /** The encrypted data section of a descriptor. Obviously the data in this is 158 * in plaintext but encrypted once encoded. */ 159 typedef struct hs_desc_encrypted_data_t { 160 /** Bitfield of CREATE2 cell supported formats. The only currently supported 161 * format is ntor. */ 162 unsigned int create2_ntor : 1; 163 164 /** A list of authentication types that a client must at least support one 165 * in order to contact the service. Contains NULL terminated strings. */ 166 smartlist_t *intro_auth_types; 167 168 /** Is this descriptor a single onion service? */ 169 unsigned int single_onion_service : 1; 170 171 /** Flow control protocol version line. */ 172 char *flow_control_pv; 173 uint8_t sendme_inc; 174 175 /** PoW parameters. If NULL, it is not present. */ 176 hs_pow_desc_params_t *pow_params; 177 178 /** A list of intro points. Contains hs_desc_intro_point_t objects. */ 179 smartlist_t *intro_points; 180 181 #ifdef TOR_UNIT_TESTS 182 /** In unit tests only, we can include additional arbitrary plaintext. 183 * This is used to test parser validation by adding invalid inner data to 184 * descriptors that are otherwise correct and correctly encrypted. */ 185 const char *test_extra_plaintext; 186 #endif 187 } hs_desc_encrypted_data_t; 188 189 /** The superencrypted data section of a descriptor. Obviously the data in 190 * this is in plaintext but encrypted once encoded. */ 191 typedef struct hs_desc_superencrypted_data_t { 192 /** This field contains ephemeral x25519 public key which is used by 193 * the encryption scheme in the client authorization. */ 194 curve25519_public_key_t auth_ephemeral_pubkey; 195 196 /** A list of authorized clients. Contains hs_desc_authorized_client_t 197 * objects. */ 198 smartlist_t *clients; 199 200 /** Decoding only: The b64-decoded encrypted blob from the descriptor */ 201 uint8_t *encrypted_blob; 202 203 /** Decoding only: Size of the encrypted_blob */ 204 size_t encrypted_blob_size; 205 } hs_desc_superencrypted_data_t; 206 207 /** Plaintext data that is unencrypted information of the descriptor. */ 208 typedef struct hs_desc_plaintext_data_t { 209 /** Version of the descriptor format. Spec specifies this field as a 210 * positive integer. */ 211 uint32_t version; 212 213 /** The lifetime of the descriptor in seconds. */ 214 uint32_t lifetime_sec; 215 216 /** Certificate with the short-term ed22519 descriptor signing key for the 217 * replica which is signed by the blinded public key for that replica. */ 218 tor_cert_t *signing_key_cert; 219 220 /** Signing public key which is used to sign the descriptor. Same public key 221 * as in the signing key certificate. */ 222 ed25519_public_key_t signing_pubkey; 223 224 /** Blinded public key used for this descriptor derived from the master 225 * identity key and generated for a specific replica number. */ 226 ed25519_public_key_t blinded_pubkey; 227 228 /** Revision counter is incremented at each upload, regardless of whether 229 * the descriptor has changed. This avoids leaking whether the descriptor 230 * has changed. Spec specifies this as a 8 bytes positive integer. */ 231 uint64_t revision_counter; 232 233 /** Decoding only: The b64-decoded superencrypted blob from the descriptor */ 234 uint8_t *superencrypted_blob; 235 236 /** Decoding only: Size of the superencrypted_blob */ 237 size_t superencrypted_blob_size; 238 } hs_desc_plaintext_data_t; 239 240 /** Service descriptor in its decoded form. */ 241 typedef struct hs_descriptor_t { 242 /** Contains the plaintext part of the descriptor. */ 243 hs_desc_plaintext_data_t plaintext_data; 244 245 /** The following contains what's in the superencrypted part of the 246 * descriptor. It's only encrypted in the encoded version of the descriptor 247 * thus the data contained in that object is in plaintext. */ 248 hs_desc_superencrypted_data_t superencrypted_data; 249 250 /** The following contains what's in the encrypted part of the descriptor. 251 * It's only encrypted in the encoded version of the descriptor thus the 252 * data contained in that object is in plaintext. */ 253 hs_desc_encrypted_data_t encrypted_data; 254 255 /** Subcredentials of a service, used by the client and service to decrypt 256 * the encrypted data. */ 257 hs_subcredential_t subcredential; 258 } hs_descriptor_t; 259 260 /** Return true iff the given descriptor format version is supported. */ 261 static inline int 262 hs_desc_is_supported_version(uint32_t version) 263 { 264 if (version < HS_DESC_SUPPORTED_FORMAT_VERSION_MIN || 265 version > HS_DESC_SUPPORTED_FORMAT_VERSION_MAX) { 266 return 0; 267 } 268 return 1; 269 } 270 271 /* Public API. */ 272 273 void hs_descriptor_free_(hs_descriptor_t *desc); 274 #define hs_descriptor_free(desc) \ 275 FREE_AND_NULL(hs_descriptor_t, hs_descriptor_free_, (desc)) 276 void hs_desc_plaintext_data_free_(hs_desc_plaintext_data_t *desc); 277 #define hs_desc_plaintext_data_free(desc) \ 278 FREE_AND_NULL(hs_desc_plaintext_data_t, hs_desc_plaintext_data_free_, (desc)) 279 void hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc); 280 #define hs_desc_superencrypted_data_free(desc) \ 281 FREE_AND_NULL(hs_desc_superencrypted_data_t, \ 282 hs_desc_superencrypted_data_free_, (desc)) 283 void hs_desc_encrypted_data_free_(hs_desc_encrypted_data_t *desc); 284 #define hs_desc_encrypted_data_free(desc) \ 285 FREE_AND_NULL(hs_desc_encrypted_data_t, hs_desc_encrypted_data_free_, (desc)) 286 287 void hs_descriptor_clear_intro_points(hs_descriptor_t *desc); 288 289 MOCK_DECL(int, 290 hs_desc_encode_descriptor,(const hs_descriptor_t *desc, 291 const ed25519_keypair_t *signing_kp, 292 const uint8_t *descriptor_cookie, 293 char **encoded_out)); 294 295 hs_desc_decode_status_t hs_desc_decode_descriptor(const char *encoded, 296 const hs_subcredential_t *subcredential, 297 const curve25519_secret_key_t *client_auth_sk, 298 hs_descriptor_t **desc_out); 299 hs_desc_decode_status_t hs_desc_decode_plaintext(const char *encoded, 300 hs_desc_plaintext_data_t *plaintext); 301 hs_desc_decode_status_t hs_desc_decode_superencrypted( 302 const hs_descriptor_t *desc, 303 hs_desc_superencrypted_data_t *desc_out); 304 hs_desc_decode_status_t hs_desc_decode_encrypted(const hs_descriptor_t *desc, 305 const curve25519_secret_key_t *client_auth_sk, 306 hs_desc_encrypted_data_t *desc_out); 307 308 size_t hs_desc_obj_size(const hs_descriptor_t *data); 309 size_t hs_desc_plaintext_obj_size(const hs_desc_plaintext_data_t *data); 310 311 hs_desc_intro_point_t *hs_desc_intro_point_new(void); 312 void hs_desc_intro_point_free_(hs_desc_intro_point_t *ip); 313 #define hs_desc_intro_point_free(ip) \ 314 FREE_AND_NULL(hs_desc_intro_point_t, hs_desc_intro_point_free_, (ip)) 315 void hs_desc_authorized_client_free_(hs_desc_authorized_client_t *client); 316 #define hs_desc_authorized_client_free(client) \ 317 FREE_AND_NULL(hs_desc_authorized_client_t, \ 318 hs_desc_authorized_client_free_, (client)) 319 320 hs_desc_authorized_client_t *hs_desc_build_fake_authorized_client(void); 321 322 void hs_desc_build_authorized_client(const hs_subcredential_t *subcredential, 323 const curve25519_public_key_t * 324 client_auth_pk, 325 const curve25519_secret_key_t * 326 auth_ephemeral_sk, 327 const uint8_t *descriptor_cookie, 328 hs_desc_authorized_client_t *client_out); 329 void hs_desc_plaintext_data_free_contents(hs_desc_plaintext_data_t *desc); 330 void hs_desc_superencrypted_data_free_contents( 331 hs_desc_superencrypted_data_t *desc); 332 void hs_desc_encrypted_data_free_contents(hs_desc_encrypted_data_t *desc); 333 334 bool hs_desc_supports_congestion_control(const hs_descriptor_t *desc); 335 336 #ifdef HS_DESCRIPTOR_PRIVATE 337 338 /* Encoding. */ 339 STATIC char *encode_link_specifiers(const smartlist_t *specs); 340 STATIC size_t build_plaintext_padding(const char *plaintext, 341 size_t plaintext_len, 342 uint8_t **padded_out); 343 /* Decoding. */ 344 STATIC smartlist_t *decode_link_specifiers(const char *encoded); 345 STATIC hs_desc_intro_point_t *decode_introduction_point( 346 const hs_descriptor_t *desc, 347 const char *text); 348 STATIC int encrypted_data_length_is_valid(size_t len); 349 STATIC int cert_is_valid(tor_cert_t *cert, uint8_t type, 350 const char *log_obj_type); 351 STATIC int desc_sig_is_valid(const char *b64_sig, 352 const ed25519_public_key_t *signing_pubkey, 353 const char *encoded_desc, size_t encoded_len); 354 355 MOCK_DECL(STATIC size_t, decrypt_desc_layer,(const hs_descriptor_t *desc, 356 const uint8_t *descriptor_cookie, 357 bool is_superencrypted_layer, 358 char **decrypted_out)); 359 360 STATIC hs_desc_decode_status_t desc_decode_encrypted_v3( 361 const hs_descriptor_t *desc, 362 const curve25519_secret_key_t *client_auth_sk, 363 hs_desc_encrypted_data_t *desc_encrypted_out); 364 365 STATIC hs_desc_decode_status_t 366 desc_decode_superencrypted_v3(const hs_descriptor_t *desc, 367 hs_desc_superencrypted_data_t * 368 desc_superencrypted_out); 369 370 MOCK_DECL(STATIC size_t, desc_decrypt_encrypted,( 371 const hs_descriptor_t *desc, 372 const curve25519_secret_key_t *client_auth_sk, 373 char **decrypted_out)); 374 375 MOCK_DECL(STATIC size_t, desc_decrypt_superencrypted,( 376 const hs_descriptor_t *desc, 377 char **decrypted_out)); 378 379 #endif /* defined(HS_DESCRIPTOR_PRIVATE) */ 380 381 #endif /* !defined(TOR_HS_DESCRIPTOR_H) */