src/or/hs_common.h

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