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 /** The default HS time period length */ 53 #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */ 54 /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */ 55 #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */ 56 /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */ 57 #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */ 58 59 /** Prefix of the onion address checksum. */ 60 #define HS_SERVICE_ADDR_CHECKSUM_PREFIX ".onion checksum" 61 /** Length of the checksum prefix minus the NUL terminated byte. */ 62 #define HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN \ 63 (sizeof(HS_SERVICE_ADDR_CHECKSUM_PREFIX) - 1) 64 /** Length of the resulting checksum of the address. The construction of this 65 * checksum looks like: 66 * CHECKSUM = ".onion checksum" || PUBKEY || VERSION 67 * where VERSION is 1 byte. This is pre-hashing. */ 68 #define HS_SERVICE_ADDR_CHECKSUM_INPUT_LEN \ 69 (HS_SERVICE_ADDR_CHECKSUM_PREFIX_LEN + ED25519_PUBKEY_LEN + sizeof(uint8_t)) 70 /** The amount of bytes we use from the address checksum. */ 71 #define HS_SERVICE_ADDR_CHECKSUM_LEN_USED 2 72 /** Length of the binary encoded service address which is of course before the 73 * base32 encoding. Construction is: 74 * PUBKEY || CHECKSUM || VERSION 75 * with 1 byte VERSION and 2 bytes CHECKSUM. The following is 35 bytes. */ 76 #define HS_SERVICE_ADDR_LEN \ 77 (ED25519_PUBKEY_LEN + HS_SERVICE_ADDR_CHECKSUM_LEN_USED + sizeof(uint8_t)) 78 /** Length of 'y' portion of 'y.onion' URL. This is base32 encoded and the 79 * length ends up to 56 bytes (not counting the terminated NUL byte.) */ 80 #define HS_SERVICE_ADDR_LEN_BASE32 \ 81 (CEIL_DIV(HS_SERVICE_ADDR_LEN * 8, 5)) 82 83 /** The default HS time period length */ 84 #define HS_TIME_PERIOD_LENGTH_DEFAULT 1440 /* 1440 minutes == one day */ 85 /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */ 86 #define HS_TIME_PERIOD_LENGTH_MIN 30 /* minutes */ 87 /** The minimum time period length as seen in prop224 section [TIME-PERIODS] */ 88 #define HS_TIME_PERIOD_LENGTH_MAX (60 * 24 * 10) /* 10 days or 14400 minutes */ 89 /** The time period rotation offset as seen in prop224 section 90 * [TIME-PERIODS] */ 91 #define HS_TIME_PERIOD_ROTATION_OFFSET (12 * 60) /* minutes */ 92 93 /** Keyblinding parameter construction is as follow: 94 * "key-blind" || INT_8(period_num) || INT_8(start_period_sec) */ 95 #define HS_KEYBLIND_NONCE_PREFIX "key-blind" 96 #define HS_KEYBLIND_NONCE_PREFIX_LEN (sizeof(HS_KEYBLIND_NONCE_PREFIX) - 1) 97 #define HS_KEYBLIND_NONCE_LEN \ 98 (HS_KEYBLIND_NONCE_PREFIX_LEN + sizeof(uint64_t) + sizeof(uint64_t)) 99 100 /** Credential and subcredential prefix value. */ 101 #define HS_CREDENTIAL_PREFIX "credential" 102 #define HS_CREDENTIAL_PREFIX_LEN (sizeof(HS_CREDENTIAL_PREFIX) - 1) 103 #define HS_SUBCREDENTIAL_PREFIX "subcredential" 104 #define HS_SUBCREDENTIAL_PREFIX_LEN (sizeof(HS_SUBCREDENTIAL_PREFIX) - 1) 105 106 /** Node hidden service stored at index prefix value. */ 107 #define HS_INDEX_PREFIX "store-at-idx" 108 #define HS_INDEX_PREFIX_LEN (sizeof(HS_INDEX_PREFIX) - 1) 109 110 /** Node hidden service directory index prefix value. */ 111 #define HSDIR_INDEX_PREFIX "node-idx" 112 #define HSDIR_INDEX_PREFIX_LEN (sizeof(HSDIR_INDEX_PREFIX) - 1) 113 114 /** Prefix of the shared random value disaster mode. */ 115 #define HS_SRV_DISASTER_PREFIX "shared-random-disaster" 116 #define HS_SRV_DISASTER_PREFIX_LEN (sizeof(HS_SRV_DISASTER_PREFIX) - 1) 117 118 /** Default value of number of hsdir replicas (hsdir_n_replicas). */ 119 #define HS_DEFAULT_HSDIR_N_REPLICAS 2 120 /** Default value of hsdir spread store (hsdir_spread_store). */ 121 #define HS_DEFAULT_HSDIR_SPREAD_STORE 4 122 /** Default value of hsdir spread fetch (hsdir_spread_fetch). */ 123 #define HS_DEFAULT_HSDIR_SPREAD_FETCH 3 124 125 /** The size of a legacy RENDEZVOUS1 cell which adds up to 168 bytes. It is 126 * bigger than the 84 bytes needed for version 3 so we need to pad up to that 127 * length so it is indistinguishable between versions. */ 128 #define HS_LEGACY_RENDEZVOUS_CELL_SIZE \ 129 (REND_COOKIE_LEN + DH1024_KEY_LEN + DIGEST_LEN) 130 131 /** Type of authentication key used by an introduction point. */ 132 typedef enum { 133 HS_AUTH_KEY_TYPE_LEGACY = 1, 134 HS_AUTH_KEY_TYPE_ED25519 = 2, 135 } hs_auth_key_type_t; 136 137 /** Return value when adding an ephemeral service through the ADD_ONION 138 * control port command. */ 139 typedef enum { 140 RSAE_BADAUTH = -5, /**< Invalid auth_type/auth_clients */ 141 RSAE_BADVIRTPORT = -4, /**< Invalid VIRTPORT/TARGET(s) */ 142 RSAE_ADDREXISTS = -3, /**< Onion address collision */ 143 RSAE_BADPRIVKEY = -2, /**< Invalid public key */ 144 RSAE_INTERNAL = -1, /**< Internal error */ 145 RSAE_OKAY = 0 /**< Service added as expected */ 146 } hs_service_add_ephemeral_status_t; 147 148 /** Represents the mapping from a virtual port of a rendezvous service to a 149 * real port on some IP. */ 150 typedef struct hs_port_config_t { 151 /** The incoming HS virtual port we're mapping */ 152 uint16_t virtual_port; 153 /** Is this an AF_UNIX port? */ 154 unsigned int is_unix_addr:1; 155 /** The outgoing TCP port to use, if !is_unix_addr */ 156 uint16_t real_port; 157 /** The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */ 158 tor_addr_t real_addr; 159 /** The socket path to connect to, if is_unix_addr */ 160 char unix_addr[FLEXIBLE_ARRAY_MEMBER]; 161 } hs_port_config_t; 162 163 void hs_init(void); 164 void hs_free_all(void); 165 166 void hs_cleanup_circ(circuit_t *circ); 167 168 int hs_check_service_private_dir(const char *username, const char *path, 169 unsigned int dir_group_readable, 170 unsigned int create); 171 int hs_get_service_max_rend_failures(void); 172 173 char *hs_path_from_filename(const char *directory, const char *filename); 174 void hs_build_address(const struct ed25519_public_key_t *key, uint8_t version, 175 char *addr_out); 176 int hs_address_is_valid(const char *address); 177 int hs_parse_address(const char *address, struct ed25519_public_key_t *key_out, 178 uint8_t *checksum_out, uint8_t *version_out); 179 int hs_parse_address_no_log(const char *address, 180 struct ed25519_public_key_t *key_out, 181 uint8_t *checksum_out, uint8_t *version_out, 182 const char **errmsg); 183 184 void hs_build_blinded_pubkey(const struct ed25519_public_key_t *pubkey, 185 const uint8_t *secret, size_t secret_len, 186 uint64_t time_period_num, 187 struct ed25519_public_key_t *pubkey_out); 188 void hs_build_blinded_keypair(const struct ed25519_keypair_t *kp, 189 const uint8_t *secret, size_t secret_len, 190 uint64_t time_period_num, 191 struct ed25519_keypair_t *kp_out); 192 int hs_service_requires_uptime_circ(const smartlist_t *ports); 193 194 routerstatus_t *pick_hsdir(const char *desc_id, const char *desc_id_base32); 195 196 struct hs_subcredential_t; 197 void hs_get_subcredential(const struct ed25519_public_key_t *identity_pk, 198 const struct ed25519_public_key_t *blinded_pk, 199 struct hs_subcredential_t *subcred_out); 200 201 uint64_t hs_get_previous_time_period_num(time_t now); 202 uint64_t hs_get_time_period_num(time_t now); 203 uint64_t hs_get_next_time_period_num(time_t now); 204 time_t hs_get_start_time_of_next_time_period(time_t now); 205 206 MOCK_DECL(int, hs_in_period_between_tp_and_srv, 207 (const networkstatus_t *consensus, time_t now)); 208 209 uint8_t *hs_get_current_srv(uint64_t time_period_num, 210 const networkstatus_t *ns); 211 uint8_t *hs_get_previous_srv(uint64_t time_period_num, 212 const networkstatus_t *ns); 213 214 void hs_build_hsdir_index(const struct ed25519_public_key_t *identity_pk, 215 const uint8_t *srv, uint64_t period_num, 216 uint8_t *hsdir_index_out); 217 void hs_build_hs_index(uint64_t replica, 218 const struct ed25519_public_key_t *blinded_pk, 219 uint64_t period_num, uint8_t *hs_index_out); 220 221 int32_t hs_get_hsdir_n_replicas(void); 222 int32_t hs_get_hsdir_spread_fetch(void); 223 int32_t hs_get_hsdir_spread_store(void); 224 225 void hs_get_responsible_hsdirs(const struct ed25519_public_key_t *blinded_pk, 226 uint64_t time_period_num, 227 int use_second_hsdir_index, 228 int for_fetching, smartlist_t *responsible_dirs); 229 routerstatus_t *hs_pick_hsdir(smartlist_t *responsible_dirs, 230 const char *req_key_str, 231 bool *is_rate_limited_out); 232 233 time_t hs_hsdir_requery_period(const or_options_t *options); 234 time_t hs_lookup_last_hid_serv_request(routerstatus_t *hs_dir, 235 const char *desc_id_base32, 236 time_t now, int set); 237 void hs_clean_last_hid_serv_requests(time_t now); 238 void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id); 239 void hs_purge_last_hid_serv_requests(void); 240 241 int hs_set_conn_addr_port(const smartlist_t *ports, edge_connection_t *conn); 242 hs_port_config_t *hs_parse_port_config(const char *string, const char *sep, 243 char **err_msg_out); 244 void hs_port_config_free_(hs_port_config_t *p); 245 #define hs_port_config_free(p) \ 246 FREE_AND_NULL(hs_port_config_t, hs_port_config_free_, (p)) 247 248 void hs_inc_rdv_stream_counter(origin_circuit_t *circ); 249 void hs_dec_rdv_stream_counter(origin_circuit_t *circ); 250 251 extend_info_t *hs_get_extend_info_from_lspecs(const smartlist_t *lspecs, 252 const struct curve25519_public_key_t *onion_key, 253 int direct_conn); 254 255 link_specifier_t *link_specifier_dup(const link_specifier_t *src); 256 257 #ifdef HS_COMMON_PRIVATE 258 259 STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_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) */ 281