hs_service.h (20990B)
1 /* Copyright (c) 2016-2021, The Tor Project, Inc. */ 2 /* See LICENSE for licensing information */ 3 4 /** 5 * \file hs_service.h 6 * \brief Header file containing service data for the HS subsystem. 7 **/ 8 9 #ifndef TOR_HS_SERVICE_H 10 #define TOR_HS_SERVICE_H 11 12 #include "lib/crypt_ops/crypto_curve25519.h" 13 #include "lib/crypt_ops/crypto_ed25519.h" 14 #include "lib/metrics/metrics_store.h" 15 16 #include "feature/hs/hs_common.h" 17 #include "feature/hs/hs_descriptor.h" 18 #include "feature/hs/hs_ident.h" 19 #include "feature/hs/hs_intropoint.h" 20 #include "feature/hs_common/replaycache.h" 21 22 /* Trunnel */ 23 #include "trunnel/hs/cell_establish_intro.h" 24 25 #include "ext/ht.h" 26 27 /** When loading and configuring a service, this is the default version it will 28 * be configured for as it is possible that no HiddenServiceVersion is 29 * present. */ 30 #define HS_SERVICE_DEFAULT_VERSION HS_VERSION_THREE 31 32 /** As described in the specification, service publishes their next descriptor 33 * at a random time between those two values (in seconds). */ 34 #define HS_SERVICE_NEXT_UPLOAD_TIME_MIN (60 * 60) 35 /** Maximum interval for uploading next descriptor (in seconds). */ 36 #define HS_SERVICE_NEXT_UPLOAD_TIME_MAX (120 * 60) 37 38 /** PoW seed expiration time is set to RAND_TIME(now+7200, 900) 39 * seconds. */ 40 #define HS_SERVICE_POW_SEED_ROTATE_TIME_MIN (7200 - 900) 41 #define HS_SERVICE_POW_SEED_ROTATE_TIME_MAX (7200) 42 43 /** Collected metrics for a specific service. */ 44 typedef struct hs_service_metrics_t { 45 /** Store containing the metrics values. */ 46 metrics_store_t *store; 47 } hs_service_metrics_t; 48 49 /** Service side introduction point. */ 50 typedef struct hs_service_intro_point_t { 51 /** Top level intropoint "shared" data between client/service. */ 52 hs_intropoint_t base; 53 54 /** Onion key of the introduction point used to extend to it for the ntor 55 * handshake. */ 56 curve25519_public_key_t onion_key; 57 58 /** Authentication keypair used to create the authentication certificate 59 * which is published in the descriptor. */ 60 ed25519_keypair_t auth_key_kp; 61 62 /** Encryption keypair for the "ntor" type. */ 63 curve25519_keypair_t enc_key_kp; 64 65 /** Blinded public ID for this service, from this intro point's 66 * active time period. */ 67 ed25519_public_key_t blinded_id; 68 69 /** Legacy key if that intro point doesn't support v3. This should be used if 70 * the base object legacy flag is set. */ 71 crypto_pk_t *legacy_key; 72 /** Legacy key SHA1 public key digest. This should be used only if the base 73 * object legacy flag is set. */ 74 uint8_t legacy_key_digest[DIGEST_LEN]; 75 76 /** Amount of INTRODUCE2 cell accepted from this intro point. */ 77 uint64_t introduce2_count; 78 79 /** Maximum number of INTRODUCE2 cell this intro point should accept. */ 80 uint64_t introduce2_max; 81 82 /** The time at which this intro point should expire and stop being used. */ 83 time_t time_to_expire; 84 85 /** The amount of circuit creation we've made to this intro point. This is 86 * incremented every time we do a circuit relaunch on this intro point which 87 * is triggered when the circuit dies but the node is still in the 88 * consensus. After MAX_INTRO_POINT_CIRCUIT_RETRIES, we give up on it. */ 89 uint32_t circuit_retries; 90 91 /** Replay cache recording the encrypted part of an INTRODUCE2 cell that the 92 * circuit associated with this intro point has received. This is used to 93 * prevent replay attacks. */ 94 replaycache_t *replay_cache; 95 96 /** Support the INTRO2 DoS defense. If set, the DoS extension described by 97 * proposal 305 is sent. */ 98 unsigned int support_intro2_dos_defense : 1; 99 } hs_service_intro_point_t; 100 101 /** Object handling introduction points of a service. */ 102 typedef struct hs_service_intropoints_t { 103 /** The time at which we've started our retry period to build circuits. We 104 * don't want to stress circuit creation so we can only retry for a certain 105 * time and then after we stop and wait. */ 106 time_t retry_period_started; 107 108 /** Number of circuit we've launched during a single retry period. */ 109 unsigned int num_circuits_launched; 110 111 /** Contains the current hs_service_intro_point_t objects indexed by 112 * authentication public key. */ 113 digest256map_t *map; 114 115 /** Contains node's identity key digest that were introduction point for this 116 * descriptor but were retried too many times. We keep those so we avoid 117 * re-picking them over and over for a circuit retry period. 118 * XXX: Once we have #22173, change this to only use ed25519 identity. */ 119 digestmap_t *failed_id; 120 } hs_service_intropoints_t; 121 122 /** Representation of a service descriptor. 123 * 124 * Some elements of the descriptor are mutable whereas others are immutable: 125 * 126 * Immutable elements are initialized once when the descriptor is built (when 127 * service descriptors gets rotated). This means that these elements are 128 * initialized once and then they don't change for the lifetime of the 129 * descriptor. See build_service_descriptor(). 130 * 131 * Mutable elements are initialized when we build the descriptor but they are 132 * also altered during the lifetime of the descriptor. They could be 133 * _refreshed_ every time we upload the descriptor (which happens multiple 134 * times over the lifetime of the descriptor), or through periodic events. We 135 * do this for elements like the descriptor revision counter and various 136 * certificates. See refresh_service_descriptor() and 137 * update_service_descriptor_intro_points(). 138 */ 139 typedef struct hs_service_descriptor_t { 140 /** Immutable: Client authorization ephemeral keypair. */ 141 curve25519_keypair_t auth_ephemeral_kp; 142 143 /** Immutable: Descriptor cookie used to encrypt the descriptor, when the 144 * client authorization is enabled */ 145 uint8_t descriptor_cookie[HS_DESC_DESCRIPTOR_COOKIE_LEN]; 146 147 /** Immutable: Descriptor signing keypair. */ 148 ed25519_keypair_t signing_kp; 149 150 /** Immutable: Blinded keypair derived from the master identity public 151 * key. */ 152 ed25519_keypair_t blinded_kp; 153 154 /** Immutable: The time period number this descriptor has been created 155 * for. */ 156 uint64_t time_period_num; 157 158 /** Immutable: The OPE cipher for encrypting revision counters for this 159 * descriptor. Tied to the descriptor blinded key. */ 160 struct crypto_ope_t *ope_cipher; 161 162 /** Mutable: Decoded descriptor. This object is used for encoding when the 163 * service publishes the descriptor. */ 164 hs_descriptor_t *desc; 165 166 /** Mutable: When is the next time when we should upload the descriptor. */ 167 time_t next_upload_time; 168 169 /** Mutable: Introduction points assign to this descriptor which contains 170 * hs_service_intropoints_t object indexed by authentication key (the RSA key 171 * if the node is legacy). */ 172 hs_service_intropoints_t intro_points; 173 174 /** Mutable: True iff we have missing intro points for this descriptor 175 * because we couldn't pick any nodes. */ 176 unsigned int missing_intro_points : 1; 177 178 /** Mutable: List of the responsible HSDirs (their b64ed identity digest) 179 * last time we uploaded this descriptor. If the set of responsible HSDirs 180 * is different from this list, this means we received new dirinfo and we 181 * need to reupload our descriptor. */ 182 smartlist_t *previous_hsdirs; 183 } hs_service_descriptor_t; 184 185 /** Service key material. */ 186 typedef struct hs_service_keys_t { 187 /** Master identify public key. */ 188 ed25519_public_key_t identity_pk; 189 /** Master identity private key. */ 190 ed25519_secret_key_t identity_sk; 191 /** True iff the key is kept offline which means the identity_sk MUST not be 192 * used in that case. */ 193 unsigned int is_identify_key_offline : 1; 194 } hs_service_keys_t; 195 196 /** Service side configuration of client authorization. */ 197 typedef struct hs_service_authorized_client_t { 198 /** The client auth public key used to encrypt the descriptor cookie. */ 199 curve25519_public_key_t client_pk; 200 } hs_service_authorized_client_t; 201 202 /** Which protocol to use for exporting HS client circuit ID. */ 203 typedef enum { 204 /** Don't expose the circuit id. */ 205 HS_CIRCUIT_ID_PROTOCOL_NONE, 206 207 /** Use the HAProxy proxy protocol. */ 208 HS_CIRCUIT_ID_PROTOCOL_HAPROXY 209 } hs_circuit_id_protocol_t; 210 211 /** Service configuration. The following are set from the torrc options either 212 * set by the configuration file or by the control port. Nothing else should 213 * change those values. */ 214 typedef struct hs_service_config_t { 215 /** Protocol version of the service. Specified by HiddenServiceVersion 216 * option. */ 217 uint32_t version; 218 219 /** Have we explicitly set HiddenServiceVersion? */ 220 unsigned int hs_version_explicitly_set : 1; 221 222 /** List of hs_port_config_t */ 223 smartlist_t *ports; 224 225 /** Path on the filesystem where the service persistent data is stored. NULL 226 * if the service is ephemeral. Specified by HiddenServiceDir option. */ 227 char *directory_path; 228 229 /** The maximum number of simultaneous streams per rendezvous circuit that 230 * are allowed to be created. No limit if 0. Specified by 231 * HiddenServiceMaxStreams option. */ 232 uint64_t max_streams_per_rdv_circuit; 233 234 /** If true, we close circuits that exceed the max_streams_per_rdv_circuit 235 * limit. Specified by HiddenServiceMaxStreamsCloseCircuit option. */ 236 unsigned int max_streams_close_circuit : 1; 237 238 /** How many introduction points this service has. Specified by 239 * HiddenServiceNumIntroductionPoints option. */ 240 unsigned int num_intro_points; 241 242 /** List of hs_service_authorized_client_t's of clients that may access this 243 * service. Specified by HiddenServiceAuthorizeClient option. */ 244 smartlist_t *clients; 245 246 /** True iff we allow request made on unknown ports. Specified by 247 * HiddenServiceAllowUnknownPorts option. */ 248 unsigned int allow_unknown_ports : 1; 249 250 /** If true, this service is a Single Onion Service. Specified by 251 * HiddenServiceSingleHopMode and HiddenServiceNonAnonymousMode options. */ 252 unsigned int is_single_onion : 1; 253 254 /** If true, allow group read permissions on the directory_path. Specified by 255 * HiddenServiceDirGroupReadable option. */ 256 unsigned int dir_group_readable : 1; 257 258 /** Is this service ephemeral? */ 259 unsigned int is_ephemeral : 1; 260 261 /** Does this service export the circuit ID of its clients? */ 262 hs_circuit_id_protocol_t circuit_id_protocol; 263 264 /** DoS defenses. For the ESTABLISH_INTRO cell extension. */ 265 unsigned int has_dos_defense_enabled : 1; 266 uint32_t intro_dos_rate_per_sec; 267 uint32_t intro_dos_burst_per_sec; 268 269 /** True iff PoW anti-DoS defenses are enabled. */ 270 unsigned int has_pow_defenses_enabled : 1; 271 uint32_t pow_queue_rate; 272 uint32_t pow_queue_burst; 273 274 /** If set, contains the Onion Balance master ed25519 public key (taken from 275 * an .onion addresses) that this tor instance serves as backend. */ 276 smartlist_t *ob_master_pubkeys; 277 } hs_service_config_t; 278 279 /** Service state. */ 280 typedef struct hs_service_state_t { 281 /** The time at which we've started our retry period to build circuits. We 282 * don't want to stress circuit creation so we can only retry for a certain 283 * time and then after we stop and wait. */ 284 time_t intro_circ_retry_started_time; 285 286 /** Number of circuit we've launched during a single retry period. This 287 * should never go over MAX_INTRO_CIRCS_PER_PERIOD. */ 288 unsigned int num_intro_circ_launched; 289 290 /** Replay cache tracking the REND_COOKIE found in INTRODUCE2 cell to detect 291 * repeats. Clients may send INTRODUCE1 cells for the same rendezvous point 292 * through two or more different introduction points; when they do, this 293 * keeps us from launching multiple simultaneous attempts to connect to the 294 * same rend point. */ 295 replaycache_t *replay_cache_rend_cookie; 296 297 /** When is the next time we should rotate our descriptors. This is has to be 298 * done at the start time of the next SRV protocol run. */ 299 time_t next_rotation_time; 300 301 /* If this is an onionbalance instance, this is an array of subcredentials 302 * that should be used when decrypting an INTRO2 cell. If this is not an 303 * onionbalance instance, this is NULL. 304 * See [ONIONBALANCE] section in rend-spec-v3.txt for more details . */ 305 hs_subcredential_t *ob_subcreds; 306 /* Number of OB subcredentials */ 307 size_t n_ob_subcreds; 308 309 /** State of the PoW defenses, which may be enabled dynamically. NULL if not 310 * defined for this service. */ 311 hs_pow_service_state_t *pow_state; 312 } hs_service_state_t; 313 314 /** Representation of a service running on this tor instance. */ 315 typedef struct hs_service_t { 316 /** Onion address base32 encoded and NUL terminated. We keep it for logging 317 * purposes so we don't have to build it every time. */ 318 char onion_address[HS_SERVICE_ADDR_LEN_BASE32 + 1]; 319 320 /** Hashtable node: use to look up the service by its master public identity 321 * key in the service global map. */ 322 HT_ENTRY(hs_service_t) hs_service_node; 323 324 /** Service state which contains various flags and counters. */ 325 hs_service_state_t state; 326 327 /** Key material of the service. */ 328 hs_service_keys_t keys; 329 330 /** Configuration of the service. */ 331 hs_service_config_t config; 332 333 /** Current descriptor. */ 334 hs_service_descriptor_t *desc_current; 335 /** Next descriptor. */ 336 hs_service_descriptor_t *desc_next; 337 338 /** Metrics. */ 339 hs_service_metrics_t metrics; 340 } hs_service_t; 341 342 /** For the service global hash map, we define a specific type for it which 343 * will make it safe to use and specific to some controlled parameters such as 344 * the hashing function and how to compare services. */ 345 typedef HT_HEAD(hs_service_ht, hs_service_t) hs_service_ht; 346 347 /* API */ 348 349 /* Global initializer and cleanup function. */ 350 void hs_service_init(void); 351 void hs_service_free_all(void); 352 353 /* Service new/free functions. */ 354 hs_service_t *hs_service_new(const or_options_t *options); 355 void hs_service_free_(hs_service_t *service); 356 /** 357 * @copydoc hs_service_free_ 358 * 359 * Additionally, set the pointer <b>s</b> to NULL. 360 **/ 361 #define hs_service_free(s) FREE_AND_NULL(hs_service_t, hs_service_free_, (s)) 362 363 hs_service_t *hs_service_find(const ed25519_public_key_t *ident_pk); 364 MOCK_DECL(unsigned int, hs_service_get_num_services,(void)); 365 void hs_service_stage_services(const smartlist_t *service_list); 366 int hs_service_load_all_keys(void); 367 int hs_service_get_version_from_key(const hs_service_t *service); 368 void hs_service_lists_fnames_for_sandbox(smartlist_t *file_list, 369 smartlist_t *dir_list); 370 int hs_service_set_conn_addr_port(const origin_circuit_t *circ, 371 edge_connection_t *conn); 372 smartlist_t *hs_service_get_metrics_stores(void); 373 374 void hs_service_map_has_changed(void); 375 void hs_service_dir_info_changed(void); 376 void hs_service_new_consensus_params(const networkstatus_t *ns); 377 void hs_service_run_scheduled_events(time_t now); 378 void hs_service_circuit_has_opened(origin_circuit_t *circ); 379 int hs_service_receive_intro_established(origin_circuit_t *circ, 380 const uint8_t *payload, 381 size_t payload_len); 382 int hs_service_receive_introduce2(origin_circuit_t *circ, 383 const uint8_t *payload, 384 size_t payload_len); 385 386 char *hs_service_lookup_current_desc(const ed25519_public_key_t *pk); 387 388 hs_service_add_ephemeral_status_t 389 hs_service_add_ephemeral(ed25519_secret_key_t *sk, smartlist_t *ports, 390 int max_streams_per_rdv_circuit, 391 int max_streams_close_circuit, 392 int pow_defenses_enabled, 393 uint32_t pow_queue_rate, 394 uint32_t pow_queue_burst, 395 smartlist_t *auth_clients_v3, char **address_out); 396 int hs_service_del_ephemeral(const char *address); 397 398 /* Used outside of the HS subsystem by the control port command HSPOST. */ 399 void hs_service_upload_desc_to_dir(const char *encoded_desc, 400 const uint8_t version, 401 const ed25519_public_key_t *identity_pk, 402 const ed25519_public_key_t *blinded_pk, 403 const routerstatus_t *hsdir_rs); 404 405 hs_circuit_id_protocol_t 406 hs_service_exports_circuit_id(const ed25519_public_key_t *pk); 407 408 void hs_service_dump_stats(int severity); 409 void hs_service_circuit_cleanup_on_close(const circuit_t *circ); 410 411 hs_service_authorized_client_t * 412 parse_authorized_client_key(const char *key_str, int severity); 413 414 void 415 service_authorized_client_free_(hs_service_authorized_client_t *client); 416 #define service_authorized_client_free(c) \ 417 FREE_AND_NULL(hs_service_authorized_client_t, \ 418 service_authorized_client_free_, (c)) 419 420 /* Config options. */ 421 int hs_service_allow_non_anonymous_connection(const or_options_t *options); 422 int hs_service_non_anonymous_mode_enabled(const or_options_t *options); 423 int hs_service_reveal_startup_time(const or_options_t *options); 424 425 #ifdef HS_SERVICE_PRIVATE 426 427 #ifdef TOR_UNIT_TESTS 428 /* Useful getters for unit tests. */ 429 STATIC unsigned int get_hs_service_map_size(void); 430 STATIC int get_hs_service_staging_list_size(void); 431 STATIC hs_service_ht *get_hs_service_map(void); 432 STATIC hs_service_t *get_first_service(void); 433 STATIC hs_service_intro_point_t *service_intro_point_find_by_ident( 434 const hs_service_t *service, 435 const hs_ident_circuit_t *ident); 436 437 MOCK_DECL(STATIC unsigned int, count_desc_circuit_established, 438 (const hs_service_descriptor_t *desc)); 439 #endif /* defined(TOR_UNIT_TESTS) */ 440 441 /* Service accessors. */ 442 STATIC hs_service_t *find_service(hs_service_ht *map, 443 const ed25519_public_key_t *pk); 444 STATIC void remove_service(hs_service_ht *map, hs_service_t *service); 445 STATIC int register_service(hs_service_ht *map, hs_service_t *service); 446 /* Service introduction point functions. */ 447 STATIC hs_service_intro_point_t *service_intro_point_new(const node_t *node); 448 STATIC void service_intro_point_free_(hs_service_intro_point_t *ip); 449 #define service_intro_point_free(ip) \ 450 FREE_AND_NULL(hs_service_intro_point_t, \ 451 service_intro_point_free_, (ip)) 452 STATIC void service_intro_point_add(digest256map_t *map, 453 hs_service_intro_point_t *ip); 454 STATIC void service_intro_point_remove(const hs_service_t *service, 455 const hs_service_intro_point_t *ip); 456 STATIC hs_service_intro_point_t *service_intro_point_find( 457 const hs_service_t *service, 458 const ed25519_public_key_t *auth_key); 459 /* Service descriptor functions. */ 460 STATIC hs_service_descriptor_t *service_descriptor_new(void); 461 STATIC hs_service_descriptor_t *service_desc_find_by_intro( 462 const hs_service_t *service, 463 const hs_service_intro_point_t *ip); 464 /* Helper functions. */ 465 STATIC int client_filename_is_valid(const char *filename); 466 STATIC hs_service_authorized_client_t * 467 parse_authorized_client(const char *client_key_str); 468 STATIC void get_objects_from_ident(const hs_ident_circuit_t *ident, 469 hs_service_t **service, 470 hs_service_intro_point_t **ip, 471 hs_service_descriptor_t **desc); 472 STATIC const node_t * 473 get_node_from_intro_point(const hs_service_intro_point_t *ip); 474 STATIC int can_service_launch_intro_circuit(hs_service_t *service, 475 time_t now); 476 STATIC int intro_point_should_expire(const hs_service_intro_point_t *ip, 477 time_t now); 478 STATIC void run_housekeeping_event(time_t now); 479 STATIC void rotate_all_descriptors(time_t now); 480 STATIC void build_all_descriptors(time_t now); 481 STATIC void update_all_descriptors_intro_points(time_t now); 482 STATIC void run_upload_descriptor_event(time_t now); 483 484 STATIC void service_descriptor_free_(hs_service_descriptor_t *desc); 485 #define service_descriptor_free(d) \ 486 FREE_AND_NULL(hs_service_descriptor_t, \ 487 service_descriptor_free_, (d)) 488 489 STATIC int 490 write_address_to_file(const hs_service_t *service, const char *fname_); 491 492 STATIC void upload_descriptor_to_all(const hs_service_t *service, 493 hs_service_descriptor_t *desc); 494 495 STATIC void service_desc_schedule_upload(hs_service_descriptor_t *desc, 496 time_t now, 497 int descriptor_changed); 498 499 STATIC int service_desc_hsdirs_changed(const hs_service_t *service, 500 const hs_service_descriptor_t *desc); 501 502 STATIC int service_authorized_client_config_equal( 503 const hs_service_config_t *config1, 504 const hs_service_config_t *config2); 505 506 STATIC void service_clear_config(hs_service_config_t *config); 507 508 #endif /* defined(HS_SERVICE_PRIVATE) */ 509 510 #endif /* !defined(TOR_HS_SERVICE_H) */