1 /* Copyright (c) 2016-2017, 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
15 #include "ed25519_cert.h"
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
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
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
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
46 /* String prefix for the signature of ESTABLISH_INTRO */
47 #define ESTABLISH_INTRO_SIG_PREFIX "Tor establish-intro cell v1"
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 */
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))
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 */
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))
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)
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)
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)
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)
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
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)
127 /* Type of authentication key used by an introduction point. */
129 HS_AUTH_KEY_TYPE_LEGACY
= 1,
130 HS_AUTH_KEY_TYPE_ED25519
= 2,
131 } hs_auth_key_type_t
;
133 /* Represents the mapping from a virtual port of a rendezvous service to a
134 * real port on some IP. */
135 typedef struct rend_service_port_config_t
{
136 /* The incoming HS virtual port we're mapping */
137 uint16_t virtual_port
;
138 /* Is this an AF_UNIX port? */
139 unsigned int is_unix_addr
:1;
140 /* The outgoing TCP port to use, if !is_unix_addr */
142 /* The outgoing IPv4 or IPv6 address to use, if !is_unix_addr */
143 tor_addr_t real_addr
;
144 /* The socket path to connect to, if is_unix_addr */
145 char unix_addr
[FLEXIBLE_ARRAY_MEMBER
];
146 } rend_service_port_config_t
;
148 /* Hidden service directory index used in a node_t which is set once we set
150 typedef struct hsdir_index_t
{
151 /* HSDir index to use when fetching a descriptor. */
152 uint8_t fetch
[DIGEST256_LEN
];
154 /* HSDir index used by services to store their first and second
155 * descriptor. The first descriptor is chronologically older than the second
156 * one and uses older TP and SRV values. */
157 uint8_t store_first
[DIGEST256_LEN
];
158 uint8_t store_second
[DIGEST256_LEN
];
162 void hs_free_all(void);
164 int hs_check_service_private_dir(const char *username
, const char *path
,
165 unsigned int dir_group_readable
,
166 unsigned int create
);
167 char *hs_path_from_filename(const char *directory
, const char *filename
);
168 void hs_build_address(const ed25519_public_key_t
*key
, uint8_t version
,
170 int hs_address_is_valid(const char *address
);
171 int hs_parse_address(const char *address
, ed25519_public_key_t
*key_out
,
172 uint8_t *checksum_out
, uint8_t *version_out
);
174 void hs_build_blinded_pubkey(const ed25519_public_key_t
*pubkey
,
175 const uint8_t *secret
, size_t secret_len
,
176 uint64_t time_period_num
,
177 ed25519_public_key_t
*pubkey_out
);
178 void hs_build_blinded_keypair(const ed25519_keypair_t
*kp
,
179 const uint8_t *secret
, size_t secret_len
,
180 uint64_t time_period_num
,
181 ed25519_keypair_t
*kp_out
);
182 int hs_service_requires_uptime_circ(const smartlist_t
*ports
);
184 void rend_data_free(rend_data_t
*data
);
185 rend_data_t
*rend_data_dup(const rend_data_t
*data
);
186 rend_data_t
*rend_data_client_create(const char *onion_address
,
189 rend_auth_type_t auth_type
);
190 rend_data_t
*rend_data_service_create(const char *onion_address
,
191 const char *pk_digest
,
192 const uint8_t *cookie
,
193 rend_auth_type_t auth_type
);
194 const char *rend_data_get_address(const rend_data_t
*rend_data
);
195 const char *rend_data_get_desc_id(const rend_data_t
*rend_data
,
196 uint8_t replica
, size_t *len_out
);
197 const uint8_t *rend_data_get_pk_digest(const rend_data_t
*rend_data
,
200 routerstatus_t
*pick_hsdir(const char *desc_id
, const char *desc_id_base32
);
202 void hs_get_subcredential(const ed25519_public_key_t
*identity_pk
,
203 const ed25519_public_key_t
*blinded_pk
,
204 uint8_t *subcred_out
);
206 uint64_t hs_get_previous_time_period_num(time_t now
);
207 uint64_t hs_get_time_period_num(time_t now
);
208 uint64_t hs_get_next_time_period_num(time_t now
);
209 time_t hs_get_start_time_of_next_time_period(time_t now
);
211 link_specifier_t
*hs_link_specifier_dup(const link_specifier_t
*lspec
);
213 MOCK_DECL(int, hs_in_period_between_tp_and_srv
,
214 (const networkstatus_t
*consensus
, time_t now
));
216 uint8_t *hs_get_current_srv(uint64_t time_period_num
,
217 const networkstatus_t
*ns
);
218 uint8_t *hs_get_previous_srv(uint64_t time_period_num
,
219 const networkstatus_t
*ns
);
221 void hs_build_hsdir_index(const ed25519_public_key_t
*identity_pk
,
222 const uint8_t *srv
, uint64_t period_num
,
223 uint8_t *hsdir_index_out
);
224 void hs_build_hs_index(uint64_t replica
,
225 const ed25519_public_key_t
*blinded_pk
,
226 uint64_t period_num
, uint8_t *hs_index_out
);
228 int32_t hs_get_hsdir_n_replicas(void);
229 int32_t hs_get_hsdir_spread_fetch(void);
230 int32_t hs_get_hsdir_spread_store(void);
232 void hs_get_responsible_hsdirs(const ed25519_public_key_t
*blinded_pk
,
233 uint64_t time_period_num
,
234 int use_second_hsdir_index
,
235 int for_fetching
, smartlist_t
*responsible_dirs
);
236 routerstatus_t
*hs_pick_hsdir(smartlist_t
*responsible_dirs
,
237 const char *req_key_str
);
239 time_t hs_hsdir_requery_period(const or_options_t
*options
);
240 time_t hs_lookup_last_hid_serv_request(routerstatus_t
*hs_dir
,
241 const char *desc_id_base32
,
242 time_t now
, int set
);
243 void hs_clean_last_hid_serv_requests(time_t now
);
244 void hs_purge_hid_serv_from_last_hid_serv_requests(const char *desc_id
);
245 void hs_purge_last_hid_serv_requests(void);
247 int hs_set_conn_addr_port(const smartlist_t
*ports
, edge_connection_t
*conn
);
249 void hs_inc_rdv_stream_counter(origin_circuit_t
*circ
);
250 void hs_dec_rdv_stream_counter(origin_circuit_t
*circ
);
252 extend_info_t
*hs_get_extend_info_from_lspecs(const smartlist_t
*lspecs
,
253 const curve25519_public_key_t
*onion_key
,
256 #ifdef HS_COMMON_PRIVATE
258 STATIC
void get_disaster_srv(uint64_t time_period_num
, uint8_t *srv_out
);
260 /** The period for which a hidden service directory cannot be queried for
261 * the same descriptor ID again. */
262 #define REND_HID_SERV_DIR_REQUERY_PERIOD (15 * 60)
263 /** Test networks generate a new consensus every 5 or 10 seconds.
264 * So allow them to requery HSDirs much faster. */
265 #define REND_HID_SERV_DIR_REQUERY_PERIOD_TESTING (5)
267 #ifdef TOR_UNIT_TESTS
269 STATIC strmap_t
*get_last_hid_serv_requests(void);
270 STATIC
uint64_t get_time_period_length(void);
272 STATIC
uint8_t *get_first_cached_disaster_srv(void);
273 STATIC
uint8_t *get_second_cached_disaster_srv(void);
275 #endif /* defined(TOR_UNIT_TESTS) */
277 #endif /* defined(HS_COMMON_PRIVATE) */
279 #endif /* !defined(TOR_HS_COMMON_H) */