src/feature/hs/hs_common.h

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