1 /* Copyright (c) 2016-2019, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
6 * \brief Header file containing common data for the whole HS subsytem.
9 #ifndef TOR_HS_COMMON_H
10 #define TOR_HS_COMMON_H
12 #include "core/or/or.h"
13 #include "lib/defs/x25519_sizes.h"
15 struct curve25519_public_key_t
;
16 struct ed25519_public_key_t
;
17 struct ed25519_keypair_t
;
20 #include "trunnel/ed25519_cert.h"
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
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
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
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
51 /* String prefix for the signature of ESTABLISH_INTRO */
52 #define ESTABLISH_INTRO_SIG_PREFIX "Tor establish-intro cell v1"
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 */
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))
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 */
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))
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)
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)
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)
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)
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
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)
132 /* Type of authentication key used by an introduction point. */
134 HS_AUTH_KEY_TYPE_LEGACY
= 1,
135 HS_AUTH_KEY_TYPE_ED25519
= 2,
136 } hs_auth_key_type_t
;
138 /* Return value when adding an ephemeral service through the ADD_ONION
139 * control port command. Both v2 and v3 share these. */
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
;
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 */
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
;
165 void hs_free_all(void);
167 void hs_cleanup_circ(circuit_t
*circ
);
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);
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
,
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
);
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
);
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
,
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
,
209 routerstatus_t
*pick_hsdir(const char *desc_id
, const char *desc_id_base32
);
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
);
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
);
220 MOCK_DECL(int, hs_in_period_between_tp_and_srv
,
221 (const networkstatus_t
*consensus
, time_t now
));
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
);
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
);
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);
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
);
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);
255 int hs_set_conn_addr_port(const smartlist_t
*ports
, edge_connection_t
*conn
);
257 void hs_inc_rdv_stream_counter(origin_circuit_t
*circ
);
258 void hs_dec_rdv_stream_counter(origin_circuit_t
*circ
);
260 extend_info_t
*hs_get_extend_info_from_lspecs(const smartlist_t
*lspecs
,
261 const struct curve25519_public_key_t
*onion_key
,
264 link_specifier_t
*link_specifier_dup(const link_specifier_t
*src
);
266 #ifdef HS_COMMON_PRIVATE
268 STATIC
void get_disaster_srv(uint64_t time_period_num
, uint8_t *srv_out
);
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)
277 #ifdef TOR_UNIT_TESTS
279 STATIC strmap_t
*get_last_hid_serv_requests(void);
280 STATIC
uint64_t get_time_period_length(void);
282 STATIC
uint8_t *get_first_cached_disaster_srv(void);
283 STATIC
uint8_t *get_second_cached_disaster_srv(void);
285 #endif /* defined(TOR_UNIT_TESTS) */
287 #endif /* defined(HS_COMMON_PRIVATE) */
289 #endif /* !defined(TOR_HS_COMMON_H) */