Tor 0.4.9.2-alpha-dev
All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
hs_common.h
Go to the documentation of this file.
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"
14
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. */
125typedef enum {
126 HS_AUTH_KEY_TYPE_LEGACY = 1,
127 HS_AUTH_KEY_TYPE_ED25519 = 2,
129
130/** Return value when adding an ephemeral service through the ADD_ONION
131 * control port command. */
132typedef 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 */
140
141/** Represents the mapping from a virtual port of a rendezvous service to a
142 * real port on some IP. */
143typedef 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 */
152 /** The socket path to connect to, if is_unix_addr */
153 char unix_addr[FLEXIBLE_ARRAY_MEMBER];
155
156void hs_init(void);
157void hs_free_all(void);
158
159void hs_cleanup_circ(circuit_t *circ);
160
161int hs_check_service_private_dir(const char *username, const char *path,
162 unsigned int dir_group_readable,
163 unsigned int create);
165
166char *hs_path_from_filename(const char *directory, const char *filename);
167void hs_build_address(const struct ed25519_public_key_t *key, uint8_t version,
168 char *addr_out);
169int hs_address_is_valid(const char *address);
170int hs_parse_address(const char *address, struct ed25519_public_key_t *key_out,
171 uint8_t *checksum_out, uint8_t *version_out);
172int 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
177void 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);
181void 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);
186
187routerstatus_t *pick_hsdir(const char *desc_id, const char *desc_id_base32);
188
189struct hs_subcredential_t;
190void 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
194uint64_t hs_get_previous_time_period_num(time_t now);
195uint64_t hs_get_time_period_num(time_t now);
196uint64_t hs_get_next_time_period_num(time_t now);
198
200 (const networkstatus_t *consensus, time_t now));
201
202uint8_t *hs_get_current_srv(uint64_t time_period_num,
203 const networkstatus_t *ns);
204uint8_t *hs_get_previous_srv(uint64_t time_period_num,
205 const networkstatus_t *ns);
206
207void 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);
210void 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
214int32_t hs_get_hsdir_n_replicas(void);
215int32_t hs_get_hsdir_spread_fetch(void);
216int32_t hs_get_hsdir_spread_store(void);
217
218void 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);
222routerstatus_t *hs_pick_hsdir(smartlist_t *responsible_dirs,
223 const char *req_key_str,
224 bool *is_rate_limited_out);
225
226time_t hs_hsdir_requery_period(const or_options_t *options);
228 const char *desc_id_base32,
229 time_t now, int set);
230void hs_clean_last_hid_serv_requests(time_t now);
231void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id);
233
235hs_port_config_t *hs_parse_port_config(const char *string, const char *sep,
236 char **err_msg_out);
238#define hs_port_config_free(p) \
239 FREE_AND_NULL(hs_port_config_t, hs_port_config_free_, (p))
240
243
245 const struct curve25519_public_key_t *onion_key,
246 int direct_conn);
247
248link_specifier_t *link_specifier_dup(const link_specifier_t *src);
249
250#ifdef HS_COMMON_PRIVATE
251
253
254STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_out);
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
270STATIC strmap_t *get_last_hid_serv_requests(void);
271STATIC uint64_t get_time_period_length(void);
272
273STATIC uint8_t *get_first_cached_disaster_srv(void);
274STATIC 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) */
void hs_get_responsible_hsdirs(const ed25519_public_key_t *blinded_pk, uint64_t time_period_num, int use_second_hsdir_index, int for_fetching, smartlist_t *responsible_dirs)
Definition: hs_common.c:1224
void hs_build_blinded_keypair(const ed25519_keypair_t *kp, const uint8_t *secret, size_t secret_len, uint64_t time_period_num, ed25519_keypair_t *blinded_kp_out)
Definition: hs_common.c:951
void hs_get_subcredential(const ed25519_public_key_t *identity_pk, const ed25519_public_key_t *blinded_pk, hs_subcredential_t *subcred_out)
Definition: hs_common.c:565
void hs_build_hs_index(uint64_t replica, const ed25519_public_key_t *blinded_pk, uint64_t period_num, uint8_t *hs_index_out)
Definition: hs_common.c:1037
void hs_build_blinded_pubkey(const ed25519_public_key_t *pk, const uint8_t *secret, size_t secret_len, uint64_t time_period_num, ed25519_public_key_t *blinded_pk_out)
Definition: hs_common.c:927
STATIC strmap_t * get_last_hid_serv_requests(void)
Definition: hs_common.c:1366
STATIC void build_blinded_key_param(const ed25519_public_key_t *pubkey, const uint8_t *secret, size_t secret_len, uint64_t period_num, uint64_t period_length, uint8_t *param_out)
Definition: hs_common.c:436
void hs_build_address(const ed25519_public_key_t *key, uint8_t version, char *addr_out)
Definition: hs_common.c:901
extend_info_t * hs_get_extend_info_from_lspecs(const smartlist_t *lspecs, const curve25519_public_key_t *onion_key, int direct_conn)
Definition: hs_common.c:1596
STATIC void get_disaster_srv(uint64_t time_period_num, uint8_t *srv_out)
Definition: hs_common.c:384
void hs_build_hsdir_index(const ed25519_public_key_t *identity_pk, const uint8_t *srv_value, uint64_t period_num, uint8_t *hsdir_index_out)
Definition: hs_common.c:1078
STATIC uint64_t get_time_period_length(void)
Definition: hs_common.c:243
hs_port_config_t * hs_parse_port_config(const char *string, const char *sep, char **err_msg_out)
Definition: hs_common.c:685
void hs_port_config_free_(hs_port_config_t *p)
Definition: hs_common.c:787
int hs_parse_address_no_log(const char *address, struct ed25519_public_key_t *key_out, uint8_t *checksum_out, uint8_t *version_out, const char **errmsg)
Definition: hs_common.c:800
routerstatus_t * hs_pick_hsdir(smartlist_t *responsible_dirs, const char *req_key_str, bool *is_rate_limited_out)
Definition: hs_common.c:1509
uint64_t hs_get_time_period_num(time_t now)
Definition: hs_common.c:269
void hs_purge_last_hid_serv_requests(void)
Definition: hs_common.c:1481
hs_service_add_ephemeral_status_t
Definition: hs_common.h:132
@ RSAE_OKAY
Definition: hs_common.h:138
@ RSAE_BADVIRTPORT
Definition: hs_common.h:134
@ RSAE_ADDREXISTS
Definition: hs_common.h:135
@ RSAE_INTERNAL
Definition: hs_common.h:137
@ RSAE_BADPRIVKEY
Definition: hs_common.h:136
@ RSAE_BADAUTH
Definition: hs_common.h:133
time_t hs_get_start_time_of_next_time_period(time_t now)
Definition: hs_common.c:324
uint8_t * hs_get_current_srv(uint64_t time_period_num, const networkstatus_t *ns)
Definition: hs_common.c:1117
uint64_t hs_get_next_time_period_num(time_t now)
Definition: hs_common.c:306
int32_t hs_get_hsdir_n_replicas(void)
Definition: hs_common.c:1152
uint8_t * hs_get_previous_srv(uint64_t time_period_num, const networkstatus_t *ns)
Definition: hs_common.c:1135
void hs_dec_rdv_stream_counter(origin_circuit_t *circ)
Definition: hs_common.c:1722
uint64_t hs_get_previous_time_period_num(time_t now)
Definition: hs_common.c:315
time_t hs_lookup_last_hid_serv_request(routerstatus_t *hs_dir, const char *desc_id_base32, time_t now, int set)
Definition: hs_common.c:1379
int hs_address_is_valid(const char *address)
Definition: hs_common.c:856
int hs_get_service_max_rend_failures(void)
Definition: hs_common.c:233
int hs_parse_address(const char *address, struct ed25519_public_key_t *key_out, uint8_t *checksum_out, uint8_t *version_out)
Definition: hs_common.c:840
void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id)
Definition: hs_common.c:1441
int32_t hs_get_hsdir_spread_fetch(void)
Definition: hs_common.c:1162
int hs_set_conn_addr_port(const smartlist_t *ports, edge_connection_t *conn)
Definition: hs_common.c:606
hs_auth_key_type_t
Definition: hs_common.h:125
time_t hs_hsdir_requery_period(const or_options_t *options)
Definition: hs_common.c:1337
void hs_init(void)
Definition: hs_common.c:1700
void hs_inc_rdv_stream_counter(origin_circuit_t *circ)
Definition: hs_common.c:1737
int hs_check_service_private_dir(const char *username, const char *path, unsigned int dir_group_readable, unsigned int create)
Definition: hs_common.c:200
void hs_clean_last_hid_serv_requests(time_t now)
Definition: hs_common.c:1413
void hs_free_all(void)
Definition: hs_common.c:1710
link_specifier_t * link_specifier_dup(const link_specifier_t *src)
Definition: hs_common.c:1751
int hs_service_requires_uptime_circ(const smartlist_t *ports)
Definition: hs_common.c:1016
int hs_in_period_between_tp_and_srv(const networkstatus_t *consensus, time_t now)
Definition: hs_common.c:987
int32_t hs_get_hsdir_spread_store(void)
Definition: hs_common.c:1172
char * hs_path_from_filename(const char *directory, const char *filename)
Definition: hs_common.c:178
Master header file for Tor-specific functionality.
char unix_addr[FLEXIBLE_ARRAY_MEMBER]
Definition: hs_common.h:153
tor_addr_t real_addr
Definition: hs_common.h:151
uint16_t real_port
Definition: hs_common.h:149
unsigned int is_unix_addr
Definition: hs_common.h:147
uint16_t virtual_port
Definition: hs_common.h:145
#define STATIC
Definition: testsupport.h:32
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
Definitions for sizes of x25519 keys and elements.