hs_common.h (12064B)
1 /* Copyright (c) 2016-2021, The Tor Project, Inc. */ 2 /* See LICENSE for licensing information */ 3 4 /** 5 * \file hs_common.h 6 * \brief Header file containing common data for the whole HS subsystem. 7 **/ 8 9 #ifndef TOR_HS_COMMON_H 10 #define TOR_HS_COMMON_H 11 12 #include "core/or/or.h" 13 #include "lib/defs/x25519_sizes.h" 14 15 struct curve25519_public_key_t; 16 struct ed25519_public_key_t; 17 struct ed25519_keypair_t; 18 19 /* Trunnel */ 20 #include "trunnel/ed25519_cert.h" 21 22 /** Version 3 of the protocol (prop224). */ 23 #define HS_VERSION_THREE 3 24 /** Earliest version we support. */ 25 #define HS_VERSION_MIN HS_VERSION_THREE 26 /** Latest version we support. */ 27 #define HS_VERSION_MAX HS_VERSION_THREE 28 29 /** Try to maintain this many intro points per service by default. */ 30 #define NUM_INTRO_POINTS_DEFAULT 3 31 /** Maximum number of intro points per generic and version 2 service. */ 32 #define NUM_INTRO_POINTS_MAX 10 33 /** Number of extra intro points we launch if our set of intro nodes is empty. 34 * See proposal 155, section 4. */ 35 #define NUM_INTRO_POINTS_EXTRA 2 36 37 /** If we can't build our intro circuits, don't retry for this long. */ 38 #define INTRO_CIRC_RETRY_PERIOD (60*5) 39 /** Don't try to build more than this many circuits before giving up for a 40 * while.*/ 41 #define MAX_INTRO_CIRCS_PER_PERIOD 10 42 /** How many times will a hidden service operator attempt to connect to a 43 * requested rendezvous point before giving up? */ 44 #define MAX_REND_FAILURES 1 45 /** How many seconds should we spend trying to connect to a requested 46 * rendezvous point before giving up? */ 47 #define MAX_REND_TIMEOUT 30 48 49 /** String prefix for the signature of ESTABLISH_INTRO */ 50 #define ESTABLISH_INTRO_SIG_PREFIX "Tor establish-intro cell v1" 51 52 /** Prefix of the onion address checksum. */ 53 #define HS_SERVICE_ADDR_CHECKSUM_PREFIX ".onion checksum" 54 /** Length of the checksum prefix minus the NUL terminated byte. */ 55 #define HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN \ 56 (sizeof(HS_SERVICE_ADDR_CHECKSUM_PREFIX) - 1) 57 /** Length of the resulting checksum of the address. The construction of this 58 * checksum looks like: 59 * CHECKSUM = ".onion checksum" || PUBKEY || VERSION 60 * where VERSION is 1 byte. This is pre-hashing. */ 61 #define HS_SERVICE_ADDR_CHECKSUM_INPUT_LEN \ 62 (HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN + ED25519_PUBKEY_LEN + sizeof(uint8_t)) 63 /** The amount of bytes we use from the address checksum. */ 64 #define HS_SERVICE_ADDR_CHECKSUM_LEN_USED 2 65 /** Length of the binary encoded service address which is of course before the 66 * base32 encoding. Construction is: 67 * PUBKEY || CHECKSUM || VERSION 68 * with 1 byte VERSION and 2 bytes CHECKSUM. The following is 35 bytes. */ 69 #define HS_SERVICE_ADDR_LEN \ 70 (ED25519_PUBKEY_LEN + HS_SERVICE_ADDR_CHECKSUM_LEN_USED + sizeof(uint8_t)) 71 /** Length of 'y' portion of 'y.onion' URL. This is base32 encoded and the 72 * length ends up to 56 bytes (not counting the terminated NUL byte.) */ 73 #define HS_SERVICE_ADDR_LEN_BASE32 \ 74 (CEIL_DIV(HS_SERVICE_ADDR_LEN * 8, 5)) 75 76 /** The default HS time period length */ 77 #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */ 78 /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */ 79 #define HS_TIME_PERIOD_LENGTH_MIN 5 /* minutes */ 80 /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */ 81 #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */ 82 /** The time period rotation offset as seen in prop224 section 83 * [TIME-PERIODS] */ 84 #define HS_TIME_PERIOD_ROTATION_OFFSET (12 * 60) /* minutes */ 85 86 /** Keyblinding parameter construction is as follow: 87 * "key-blind" || INT_8(period_num) || INT_8(start_period_sec) */ 88 #define HS_KEYBLIND_NONCE_PREFIX "key-blind" 89 #define HS_KEYBLIND_NONCE_PREFIX_LEN (sizeof(HS_KEYBLIND_NONCE_PREFIX) - 1) 90 #define HS_KEYBLIND_NONCE_LEN \ 91 (HS_KEYBLIND_NONCE_PREFIX_LEN + sizeof(uint64_t) + sizeof(uint64_t)) 92 93 /** Credential and subcredential prefix value. */ 94 #define HS_CREDENTIAL_PREFIX "credential" 95 #define HS_CREDENTIAL_PREFIX_LEN (sizeof(HS_CREDENTIAL_PREFIX) - 1) 96 #define HS_SUBCREDENTIAL_PREFIX "subcredential" 97 #define HS_SUBCREDENTIAL_PREFIX_LEN (sizeof(HS_SUBCREDENTIAL_PREFIX) - 1) 98 99 /** Node hidden service stored at index prefix value. */ 100 #define HS_INDEX_PREFIX "store-at-idx" 101 #define HS_INDEX_PREFIX_LEN (sizeof(HS_INDEX_PREFIX) - 1) 102 103 /** Node hidden service directory index prefix value. */ 104 #define HSDIR_INDEX_PREFIX "node-idx" 105 #define HSDIR_INDEX_PREFIX_LEN (sizeof(HSDIR_INDEX_PREFIX) - 1) 106 107 /** Prefix of the shared random value disaster mode. */ 108 #define HS_SRV_DISASTER_PREFIX "shared-random-disaster" 109 #define HS_SRV_DISASTER_PREFIX_LEN (sizeof(HS_SRV_DISASTER_PREFIX) - 1) 110 111 /** Default value of number of hsdir replicas (hsdir_n_replicas). */ 112 #define HS_DEFAULT_HSDIR_N_REPLICAS 2 113 /** Default value of hsdir spread store (hsdir_spread_store). */ 114 #define HS_DEFAULT_HSDIR_SPREAD_STORE 4 115 /** Default value of hsdir spread fetch (hsdir_spread_fetch). */ 116 #define HS_DEFAULT_HSDIR_SPREAD_FETCH 3 117 118 /** The size of a legacy RENDEZVOUS1 cell which adds up to 168 bytes. It is 119 * bigger than the 84 bytes needed for version 3 so we need to pad up to that 120 * length so it is indistinguishable between versions. */ 121 #define HS_LEGACY_RENDEZVOUS_CELL_SIZE \ 122 (REND_COOKIE_LEN + DH1024_KEY_LEN + DIGEST_LEN) 123 124 /** Type of authentication key used by an introduction point. */ 125 typedef enum { 126 HS_AUTH_KEY_TYPE_LEGACY = 1, 127 HS_AUTH_KEY_TYPE_ED25519 = 2, 128 } hs_auth_key_type_t; 129 130 /** Return value when adding an ephemeral service through the ADD_ONION 131 * control port command. */ 132 typedef enum { 133 RSAE_BADAUTH = -5, /**< Invalid auth_type/auth_clients */ 134 RSAE_BADVIRTPORT = -4, /**< Invalid VIRTPORT/TARGET(s) */ 135 RSAE_ADDREXISTS = -3, /**< Onion address collision */ 136 RSAE_BADPRIVKEY = -2, /**< Invalid public key */ 137 RSAE_INTERNAL = -1, /**< Internal error */ 138 RSAE_OKAY = 0 /**< Service added as expected */ 139 } hs_service_add_ephemeral_status_t; 140 141 /** Represents the mapping from a virtual port of a rendezvous service to a 142 * real port on some IP. */ 143 typedef struct hs_port_config_t { 144 /** The incoming HS virtual port we're mapping */ 145 uint16_t virtual_port; 146 /** Is this an AF_UNIX port? */ 147 unsigned int is_unix_addr:1; 148 /** The outgoing TCP port to use, if !is_unix_addr */ 149 uint16_t real_port; 150 /** The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */ 151 tor_addr_t real_addr; 152 /** The socket path to connect to, if is_unix_addr */ 153 char unix_addr[FLEXIBLE_ARRAY_MEMBER]; 154 } hs_port_config_t; 155 156 void hs_init(void); 157 void hs_free_all(void); 158 159 void hs_cleanup_circ(circuit_t *circ); 160 161 int hs_check_service_private_dir(const char *username, const char *path, 162 unsigned int dir_group_readable, 163 unsigned int create); 164 int hs_get_service_max_rend_failures(void); 165 166 char *hs_path_from_filename(const char *directory, const char *filename); 167 void hs_build_address(const struct ed25519_public_key_t *key, uint8_t version, 168 char *addr_out); 169 int hs_address_is_valid(const char *address); 170 int hs_parse_address(const char *address, struct ed25519_public_key_t *key_out, 171 uint8_t *checksum_out, uint8_t *version_out); 172 int hs_parse_address_no_log(const char *address, 173 struct ed25519_public_key_t *key_out, 174 uint8_t *checksum_out, uint8_t *version_out, 175 const char **errmsg); 176 177 void hs_build_blinded_pubkey(const struct ed25519_public_key_t *pubkey, 178 const uint8_t *secret, size_t secret_len, 179 uint64_t time_period_num, 180 struct ed25519_public_key_t *pubkey_out); 181 void hs_build_blinded_keypair(const struct ed25519_keypair_t *kp, 182 const uint8_t *secret, size_t secret_len, 183 uint64_t time_period_num, 184 struct ed25519_keypair_t *kp_out); 185 int hs_service_requires_uptime_circ(const smartlist_t *ports); 186 187 routerstatus_t *pick_hsdir(const char *desc_id, const char *desc_id_base32); 188 189 struct hs_subcredential_t; 190 void hs_get_subcredential(const struct ed25519_public_key_t *identity_pk, 191 const struct ed25519_public_key_t *blinded_pk, 192 struct hs_subcredential_t *subcred_out); 193 194 uint64_t hs_get_previous_time_period_num(time_t now); 195 uint64_t hs_get_time_period_num(time_t now); 196 uint64_t hs_get_next_time_period_num(time_t now); 197 time_t hs_get_start_time_of_next_time_period(time_t now); 198 199 MOCK_DECL(int, hs_in_period_between_tp_and_srv, 200 (const networkstatus_t *consensus, time_t now)); 201 202 uint8_t *hs_get_current_srv(uint64_t time_period_num, 203 const networkstatus_t *ns); 204 uint8_t *hs_get_previous_srv(uint64_t time_period_num, 205 const networkstatus_t *ns); 206 207 void hs_build_hsdir_index(const struct ed25519_public_key_t *identity_pk, 208 const uint8_t *srv, uint64_t period_num, 209 uint8_t *hsdir_index_out); 210 void hs_build_hs_index(uint64_t replica, 211 const struct ed25519_public_key_t *blinded_pk, 212 uint64_t period_num, uint8_t *hs_index_out); 213 214 int32_t hs_get_hsdir_n_replicas(void); 215 int32_t hs_get_hsdir_spread_fetch(void); 216 int32_t hs_get_hsdir_spread_store(void); 217 218 void hs_get_responsible_hsdirs(const struct ed25519_public_key_t *blinded_pk, 219 uint64_t time_period_num, 220 int use_second_hsdir_index, 221 int for_fetching, smartlist_t *responsible_dirs); 222 routerstatus_t *hs_pick_hsdir(smartlist_t *responsible_dirs, 223 const char *req_key_str, 224 bool *is_rate_limited_out); 225 226 time_t hs_hsdir_requery_period(const or_options_t *options); 227 time_t hs_lookup_last_hid_serv_request(routerstatus_t *hs_dir, 228 const char *desc_id_base32, 229 time_t now, int set); 230 void hs_clean_last_hid_serv_requests(time_t now); 231 void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id); 232 void hs_purge_last_hid_serv_requests(void); 233 234 int hs_set_conn_addr_port(const smartlist_t *ports, edge_connection_t *conn); 235 hs_port_config_t *hs_parse_port_config(const char *string, const char *sep, 236 char **err_msg_out); 237 void hs_port_config_free_(hs_port_config_t *p); 238 #define hs_port_config_free(p) \ 239 FREE_AND_NULL(hs_port_config_t, hs_port_config_free_, (p)) 240 241 void hs_inc_rdv_stream_counter(origin_circuit_t *circ); 242 void hs_dec_rdv_stream_counter(origin_circuit_t *circ); 243 244 extend_info_t *hs_get_extend_info_from_lspecs(const smartlist_t *lspecs, 245 const struct curve25519_public_key_t *onion_key, 246 int direct_conn); 247 248 link_specifier_t *link_specifier_dup(const link_specifier_t *src); 249 250 #ifdef HS_COMMON_PRIVATE 251 252 struct ed25519_public_key_t; 253 254 STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_out); 255 STATIC void build_blinded_key_param( 256 const struct ed25519_public_key_t *pubkey, 257 const uint8_t *secret, size_t secret_len, 258 uint64_t period_num, uint64_t period_length, 259 uint8_t *param_out); 260 261 /** The period for which a hidden service directory cannot be queried for 262 * the same descriptor ID again. */ 263 #define REND_HID_SERV_DIR_REQUERY_PERIOD (15 * 60) 264 /** Test networks generate a new consensus every 5 or 10 seconds. 265 * So allow them to requery HSDirs much faster. */ 266 #define REND_HID_SERV_DIR_REQUERY_PERIOD_TESTING (5) 267 268 #ifdef TOR_UNIT_TESTS 269 270 STATIC strmap_t *get_last_hid_serv_requests(void); 271 STATIC uint64_t get_time_period_length(void); 272 273 STATIC uint8_t *get_first_cached_disaster_srv(void); 274 STATIC uint8_t *get_second_cached_disaster_srv(void); 275 276 #endif /* defined(TOR_UNIT_TESTS) */ 277 278 #endif /* defined(HS_COMMON_PRIVATE) */ 279 280 #endif /* !defined(TOR_HS_COMMON_H) */