Tor  0.4.5.0-alpha-dev
hs_client.h
Go to the documentation of this file.
1 /* Copyright (c) 2017-2020, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
3 
4 /**
5  * \file hs_client.h
6  * \brief Header file containing client data for the HS subsytem.
7  **/
8 
9 #ifndef TOR_HS_CLIENT_H
10 #define TOR_HS_CLIENT_H
11 
13 
14 #include "feature/hs/hs_circuit.h"
16 #include "feature/hs/hs_ident.h"
17 
18 /** Status code of a descriptor fetch request. */
19 typedef enum {
20  /** Something internally went wrong. */
22  /** The fetch request has been launched successfully. */
24  /** We already have a usable descriptor. No fetch. */
26  /** No more HSDir available to query. */
28  /** The fetch request is not allowed. */
30  /** We are missing information to be able to launch a request. */
32  /** There is a pending fetch for the requested service. */
35 
36 /* Status code of client auth credential registration */
37 typedef enum {
38  /* We successfuly registered these credentials */
39  REGISTER_SUCCESS,
40  /* We successfully registered these credentials, but had to replace some
41  * existing ones. */
42  REGISTER_SUCCESS_ALREADY_EXISTS,
43  /* We successfuly registered these credentials, and also decrypted a cached
44  * descriptor. */
45  REGISTER_SUCCESS_AND_DECRYPTED,
46  /* We failed to register these credentials, because of a bad HS address. */
47  REGISTER_FAIL_BAD_ADDRESS,
48  /* We failed to store these credentials in a persistent file on disk. */
49  REGISTER_FAIL_PERMANENT_STORAGE,
50 } hs_client_register_auth_status_t;
51 
52 /* Status code of client auth credential removal */
53 typedef enum {
54  /* We successfuly removed these credentials */
55  REMOVAL_SUCCESS,
56  /* No need to remove those credentials, because they were not there. */
57  REMOVAL_SUCCESS_NOT_FOUND,
58  /* We failed to register these credentials, because of a bad HS address. */
59  REMOVAL_BAD_ADDRESS,
60 } hs_client_removal_auth_status_t;
61 
62 /** Flag to set when a client auth is permanent (saved on disk). */
63 #define CLIENT_AUTH_FLAG_IS_PERMANENT (1<<0)
64 
65 /** Client-side configuration of client authorization */
67  /** An curve25519 secret key used to compute decryption keys that
68  * allow the client to decrypt the hidden service descriptor. */
70 
71  /** An onion address that is used to connect to the onion service. */
73 
74  /** An client name used to connect to the onion service. */
75  char *client_name;
76 
77  /* Optional flags for this client. */
78  int flags;
80 
81 hs_client_register_auth_status_t
83 
84 hs_client_removal_auth_status_t
85 hs_client_remove_auth_credentials(const char *hsaddress);
86 
87 digest256map_t *get_hs_client_auths_map(void);
88 
89 #define client_service_authorization_free(auth) \
90  FREE_AND_NULL(hs_client_service_authorization_t, \
91  client_service_authorization_free_, (auth))
92 
93 void
94 client_service_authorization_free_(hs_client_service_authorization_t *auth);
95 
97  const edge_connection_t *conn);
98 
100  const ed25519_public_key_t *onion_identity_pk,
101  const smartlist_t *hsdirs);
102 
104  const char *desc_str,
105  const ed25519_public_key_t *service_identity_pk,
106  hs_descriptor_t **desc);
108  const hs_descriptor_t *desc);
109 int hs_client_refetch_hsdesc(const ed25519_public_key_t *identity_pk);
110 void hs_client_dir_info_changed(void);
111 
113  origin_circuit_t *rend_circ);
114 
118 
120  const uint8_t *payload,
121  size_t payload_len);
123  const uint8_t *payload,
124  size_t payload_len);
126  const uint8_t *payload,
127  size_t payload_len);
128 
129 void hs_client_dir_fetch_done(dir_connection_t *dir_conn, const char *reason,
130  const char *body, const int status_code);
131 
133  const edge_connection_t *edge_conn);
134 
136  int validate_only);
137 
140 
141 void hs_client_purge_state(void);
142 
143 void hs_client_free_all(void);
144 
145 #ifdef HS_CLIENT_PRIVATE
146 
147 STATIC int auth_key_filename_is_valid(const char *filename);
148 
150 parse_auth_file_content(const char *client_key_str);
151 
153 pick_hsdir_v3(const ed25519_public_key_t *onion_identity_pk);
154 
157 
160 
161 STATIC int handle_rendezvous2(origin_circuit_t *circ, const uint8_t *payload,
162  size_t payload_len);
163 
165  fetch_v3_desc, (const ed25519_public_key_t *onion_identity_pk));
166 
168 
170 
171 #ifdef TOR_UNIT_TESTS
172 
173 STATIC void set_hs_client_auths_map(digest256map_t *map);
174 
175 #endif /* defined(TOR_UNIT_TESTS) */
176 
177 #endif /* defined(HS_CLIENT_PRIVATE) */
178 
179 #endif /* !defined(TOR_HS_CLIENT_H) */
HS_CLIENT_FETCH_HAVE_DESC
@ HS_CLIENT_FETCH_HAVE_DESC
Definition: hs_client.h:25
hs_client_register_auth_credentials
hs_client_register_auth_status_t hs_client_register_auth_credentials(hs_client_service_authorization_t *creds)
Definition: hs_client.c:1652
hs_desc_decode_status_t
hs_desc_decode_status_t
Definition: hs_descriptor.h:74
hs_ident.h
Header file containing circuit and connection identifier data for the whole HS subsytem.
hs_client_circuit_cleanup_on_free
void hs_client_circuit_cleanup_on_free(const circuit_t *circ)
Definition: hs_client.c:1898
hs_client_fetch_status_t
hs_client_fetch_status_t
Definition: hs_client.h:19
desc_intro_point_to_extend_info
STATIC extend_info_t * desc_intro_point_to_extend_info(const hs_desc_intro_point_t *ip)
Definition: hs_client.c:814
HS_CLIENT_FETCH_ERROR
@ HS_CLIENT_FETCH_ERROR
Definition: hs_client.h:21
hs_config_client_authorization
int hs_config_client_authorization(const or_options_t *options, int validate_only)
Definition: hs_client.c:2301
HS_CLIENT_FETCH_NO_HSDIRS
@ HS_CLIENT_FETCH_NO_HSDIRS
Definition: hs_client.h:27
hs_client_receive_rendezvous_acked
int hs_client_receive_rendezvous_acked(origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
Definition: hs_client.c:2127
parse_auth_file_content
STATIC hs_client_service_authorization_t * parse_auth_file_content(const char *client_key_str)
Definition: hs_client.c:2224
hs_client_circuit_has_opened
void hs_client_circuit_has_opened(origin_circuit_t *circ)
Definition: hs_client.c:2097
hs_client_launch_v3_desc_fetch
void hs_client_launch_v3_desc_fetch(const ed25519_public_key_t *onion_identity_pk, const smartlist_t *hsdirs)
Definition: hs_client.c:486
hs_client_receive_introduce_ack
int hs_client_receive_introduce_ack(origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
Definition: hs_client.c:2438
hs_client_circuit_cleanup_on_close
void hs_client_circuit_cleanup_on_close(const circuit_t *circ)
Definition: hs_client.c:1867
HS_CLIENT_FETCH_MISSING_INFO
@ HS_CLIENT_FETCH_MISSING_INFO
Definition: hs_client.h:31
routerstatus_t
Definition: routerstatus_st.h:19
HS_CLIENT_FETCH_NOT_ALLOWED
@ HS_CLIENT_FETCH_NOT_ALLOWED
Definition: hs_client.h:29
hs_client_any_intro_points_usable
int hs_client_any_intro_points_usable(const ed25519_public_key_t *service_pk, const hs_descriptor_t *desc)
Definition: hs_client.c:2031
get_hs_client_auths_map
digest256map_t * get_hs_client_auths_map(void)
Definition: hs_client.c:1855
pick_hsdir_v3
STATIC routerstatus_t * pick_hsdir_v3(const ed25519_public_key_t *onion_identity_pk)
Definition: hs_client.c:430
hs_client_remove_auth_credentials
hs_client_removal_auth_status_t hs_client_remove_auth_credentials(const char *hsaddress)
Definition: hs_client.c:1821
handle_rendezvous2
STATIC int handle_rendezvous2(origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
Definition: hs_client.c:1228
hs_client_note_connection_attempt_succeeded
void hs_client_note_connection_attempt_succeeded(const edge_connection_t *conn)
Definition: hs_client.c:1948
hs_client_receive_rendezvous2
int hs_client_receive_rendezvous2(origin_circuit_t *circ, const uint8_t *payload, size_t payload_len)
Definition: hs_client.c:2467
origin_circuit_t
Definition: origin_circuit_st.h:79
ed25519_public_key_t
Definition: crypto_ed25519.h:23
hs_client_free_all
void hs_client_free_all(void)
Definition: hs_client.c:2580
hs_client_dir_fetch_done
void hs_client_dir_fetch_done(dir_connection_t *dir_conn, const char *reason, const char *body, const int status_code)
Definition: hs_client.c:2391
circuit_t
Definition: circuit_st.h:61
hs_client_send_introduce1
int hs_client_send_introduce1(origin_circuit_t *intro_circ, origin_circuit_t *rend_circ)
Definition: hs_client.c:2085
hs_descriptor_t
Definition: hs_descriptor.h:226
MOCK_DECL
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
fetch_v3_desc
STATIC hs_client_fetch_status_t fetch_v3_desc(const ed25519_public_key_t *onion_identity_pk)
Definition: hs_client.c:467
hs_client_service_authorization_t
Definition: hs_client.h:66
HS_CLIENT_FETCH_LAUNCHED
@ HS_CLIENT_FETCH_LAUNCHED
Definition: hs_client.h:23
hs_client_dir_info_changed
void hs_client_dir_info_changed(void)
Definition: hs_client.c:2612
hs_client_refetch_hsdesc
int hs_client_refetch_hsdesc(const ed25519_public_key_t *identity_pk)
Definition: hs_client.c:2054
hs_client_service_authorization_t::client_name
char * client_name
Definition: hs_client.h:75
purge_ephemeral_client_auth
STATIC void purge_ephemeral_client_auth(void)
Definition: hs_client.c:1358
hs_client_service_authorization_t::enc_seckey
curve25519_secret_key_t enc_seckey
Definition: hs_client.h:69
curve25519_secret_key_t
Definition: crypto_curve25519.h:33
hs_client_purge_state
void hs_client_purge_state(void)
Definition: hs_client.c:2590
hs_client_get_random_intro_from_edge
extend_info_t * hs_client_get_random_intro_from_edge(const edge_connection_t *edge_conn)
Definition: hs_client.c:2425
hs_client_decode_descriptor
hs_desc_decode_status_t hs_client_decode_descriptor(const char *desc_str, const ed25519_public_key_t *service_identity_pk, hs_descriptor_t **desc)
Definition: hs_client.c:1974
hs_client_reextend_intro_circuit
int hs_client_reextend_intro_circuit(origin_circuit_t *circ)
Definition: hs_client.c:2505
edge_connection_t
Definition: edge_connection_st.h:21
client_get_random_intro
STATIC extend_info_t * client_get_random_intro(const ed25519_public_key_t *service_pk)
Definition: hs_client.c:876
retry_all_socks_conn_waiting_for_desc
STATIC void retry_all_socks_conn_waiting_for_desc(void)
Definition: hs_client.c:299
or_options_t
Definition: or_options_st.h:45
STATIC
#define STATIC
Definition: testsupport.h:32
dir_connection_t
Definition: dir_connection_st.h:21
hs_circuit.h
Header file containing circuit data for the whole HS subsytem.
crypto_ed25519.h
Header for crypto_ed25519.c.
hs_desc_intro_point_t
Definition: hs_descriptor.h:99
HS_CLIENT_FETCH_PENDING
@ HS_CLIENT_FETCH_PENDING
Definition: hs_client.h:33
hs_descriptor.h
Header file for hs_descriptor.c.
hs_client_close_intro_circuits_from_desc
void hs_client_close_intro_circuits_from_desc(const hs_descriptor_t *desc)
Definition: hs_client.c:2554
smartlist_t
Definition: smartlist_core.h:26
HS_SERVICE_ADDR_LEN_BASE32
#define HS_SERVICE_ADDR_LEN_BASE32
Definition: hs_common.h:83
extend_info_t
Definition: extend_info_st.h:27
hs_client_service_authorization_t::onion_address
char onion_address[HS_SERVICE_ADDR_LEN_BASE32+1]
Definition: hs_client.h:72
auth_key_filename_is_valid
STATIC int auth_key_filename_is_valid(const char *filename)
Definition: hs_client.c:2197