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 3
 118 /* Default value of hsdir spread fetch (hsdir_spread_fetch). */
 119 #define HS_DEFAULT_HSDIR_SPREAD_FETCH 3
 120
 121 /* Type of authentication key used by an introduction point. */
 122 typedef enum {
 123   HS_AUTH_KEY_TYPE_LEGACY  = 1,
 124   HS_AUTH_KEY_TYPE_ED25519 = 2,
 125 } hs_auth_key_type_t;
 126
 127 /* Represents the mapping from a virtual port of a rendezvous service to a
 128  * real port on some IP. */
 129 typedef struct rend_service_port_config_t {
 130   /* The incoming HS virtual port we're mapping */
 131   uint16_t virtual_port;
 132   /* Is this an AF_UNIX port? */
 133   unsigned int is_unix_addr:1;
 134   /* The outgoing TCP port to use, if !is_unix_addr */
 135   uint16_t real_port;
 136   /* The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */
 137   tor_addr_t real_addr;
 138   /* The socket path to connect to, if is_unix_addr */
 139   char unix_addr[FLEXIBLE_ARRAY_MEMBER];
 140 } rend_service_port_config_t;
 141
 142 /* Hidden service directory index used in a node_t which is set once we set
 143  * the consensus. */
 144 typedef struct hsdir_index_t {
 145   /* The hsdir index for the current time period. */
 146   uint8_t current[DIGEST256_LEN];
 147   /* The hsdir index for the next time period. */
 148   uint8_t next[DIGEST256_LEN];
 149 } hsdir_index_t;
 150
 151 void hs_init(void);
 152 void hs_free_all(void);
 153
 154 int hs_check_service_private_dir(const char *username, const char *path,
 155                                  unsigned int dir_group_readable,
 156                                  unsigned int create);
 157 char *hs_path_from_filename(const char *directory, const char *filename);
 158 void hs_build_address(const ed25519_public_key_t *key, uint8_t version,
 159                       char *addr_out);
 160 int hs_address_is_valid(const char *address);
 161 int hs_parse_address(const char *address, ed25519_public_key_t *key_out,
 162                      uint8_t *checksum_out, uint8_t *version_out);
 163
 164 void hs_build_blinded_pubkey(const ed25519_public_key_t *pubkey,
 165                              const uint8_t *secret, size_t secret_len,
 166                              uint64_t time_period_num,
 167                              ed25519_public_key_t *pubkey_out);
 168 void hs_build_blinded_keypair(const ed25519_keypair_t *kp,
 169                               const uint8_t *secret, size_t secret_len,
 170                               uint64_t time_period_num,
 171                               ed25519_keypair_t *kp_out);
 172 int hs_service_requires_uptime_circ(const smartlist_t *ports);
 173
 174 void rend_data_free(rend_data_t *data);
 175 rend_data_t *rend_data_dup(const rend_data_t *data);
 176 rend_data_t *rend_data_client_create(const char *onion_address,
 177                                      const char *desc_id,
 178                                      const char *cookie,
 179                                      rend_auth_type_t auth_type);
 180 rend_data_t *rend_data_service_create(const char *onion_address,
 181                                       const char *pk_digest,
 182                                       const uint8_t *cookie,
 183                                       rend_auth_type_t auth_type);
 184 const char *rend_data_get_address(const rend_data_t *rend_data);
 185 const char *rend_data_get_desc_id(const rend_data_t *rend_data,
 186                                   uint8_t replica, size_t *len_out);
 187 const uint8_t *rend_data_get_pk_digest(const rend_data_t *rend_data,
 188                                        size_t *len_out);
 189
 190 routerstatus_t *pick_hsdir(const char *desc_id, const char *desc_id_base32);
 191
 192 void hs_get_subcredential(const ed25519_public_key_t *identity_pk,
 193                           const ed25519_public_key_t *blinded_pk,
 194                           uint8_t *subcred_out);
 195
 196 uint64_t hs_get_time_period_num(time_t now);
 197 uint64_t hs_get_next_time_period_num(time_t now);
 198 time_t hs_get_start_time_of_next_time_period(time_t now);
 199
 200 link_specifier_t *hs_link_specifier_dup(const link_specifier_t *lspec);
 201
 202 MOCK_DECL(int, hs_overlap_mode_is_active,
 203           (const networkstatus_t *consensus, time_t now));
 204
 205 uint8_t *hs_get_current_srv(uint64_t time_period_num,
 206                             const networkstatus_t *ns);
 207 uint8_t *hs_get_previous_srv(uint64_t time_period_num,
 208                              const networkstatus_t *ns);
 209
 210 void hs_build_hsdir_index(const ed25519_public_key_t *identity_pk,
 211                           const uint8_t *srv, uint64_t period_num,
 212                           uint8_t *hsdir_index_out);
 213 void hs_build_hs_index(uint64_t replica,
 214                        const ed25519_public_key_t *blinded_pk,
 215                        uint64_t period_num, uint8_t *hs_index_out);
 216
 217 int32_t hs_get_hsdir_n_replicas(void);
 218 int32_t hs_get_hsdir_spread_fetch(void);
 219 int32_t hs_get_hsdir_spread_store(void);
 220
 221 void hs_get_responsible_hsdirs(const ed25519_public_key_t *blinded_pk,
 222                                uint64_t time_period_num, int is_next_period,
 223                                int is_client, smartlist_t *responsible_dirs);
 224 routerstatus_t *hs_pick_hsdir(smartlist_t *responsible_dirs,
 225                               const char *req_key_str);
 226
 227 time_t hs_hsdir_requery_period(const or_options_t *options);
 228 time_t hs_lookup_last_hid_serv_request(routerstatus_t *hs_dir,
 229                                        const char *desc_id_base32,
 230                                        time_t now, int set);
 231 void hs_clean_last_hid_serv_requests(time_t now);
 232 void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id);
 233 void hs_purge_last_hid_serv_requests(void);
 234
 235 int hs_set_conn_addr_port(const smartlist_t *ports, edge_connection_t *conn);
 236
 237 void hs_inc_rdv_stream_counter(origin_circuit_t *circ);
 238 void hs_dec_rdv_stream_counter(origin_circuit_t *circ);
 239
 240 #ifdef HS_COMMON_PRIVATE
 241
 242 STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_out);
 243
 244 /** The period for which a hidden service directory cannot be queried for
 245  * the same descriptor ID again. */
 246 #define REND_HID_SERV_DIR_REQUERY_PERIOD (15 * 60)
 247 /** Test networks generate a new consensus every 5 or 10 seconds.
 248  * So allow them to requery HSDirs much faster. */
 249 #define REND_HID_SERV_DIR_REQUERY_PERIOD_TESTING (5)
 250
 251 #ifdef TOR_UNIT_TESTS
 252
 253 STATIC strmap_t *get_last_hid_serv_requests(void);
 254 STATIC uint64_t get_time_period_length(void);
 255
 256 STATIC uint8_t *get_first_cached_disaster_srv(void);
 257 STATIC uint8_t *get_second_cached_disaster_srv(void);
 258
 259 #endif /* TOR_UNIT_TESTS */
 260
 261 #endif /* HS_COMMON_PRIVATE */
 262
 263 #endif /* TOR_HS_COMMON_H */
 264