Tor  0.4.7.0-alpha-dev
hs_ident.h
Go to the documentation of this file.
1 /* Copyright (c) 2017-2021, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
3 
4 /**
5  * \file hs_ident.h
6  * \brief Header file containing circuit and connection identifier data for
7  * the whole HS subsystem.
8  *
9  * \details
10  * This interface is used to uniquely identify a hidden service on a circuit
11  * or connection using the service identity public key. Once the circuit or
12  * connection subsystem calls in the hidden service one, we use those
13  * identifiers to lookup the corresponding objects like service, intro point
14  * and descriptor.
15  *
16  * Furthermore, the circuit identifier holds cryptographic material needed for
17  * the e2e encryption on the rendezvous circuit which is set once the
18  * rendezvous circuit has opened and ready to be used.
19  **/
20 
21 #ifndef TOR_HS_IDENT_H
22 #define TOR_HS_IDENT_H
23 
25 
26 #include "feature/hs/hs_common.h"
27 
28 /** Length of the rendezvous cookie that is used to connect circuits at the
29  * rendezvous point. */
30 #define HS_REND_COOKIE_LEN DIGEST_LEN
31 
32 /** Type of circuit an hs_ident_t object is associated with. */
33 typedef enum {
34  HS_IDENT_CIRCUIT_INTRO = 1,
35  HS_IDENT_CIRCUIT_RENDEZVOUS = 2,
37 
38 /** Client and service side circuit identifier that is used for hidden service
39  * circuit establishment. Not all fields contain data, it depends on the
40  * circuit purpose. This is attached to an origin_circuit_t. All fields are
41  * used by both client and service. */
42 typedef struct hs_ident_circuit_t {
43  /** (All circuit) The public key used to uniquely identify the service. It is
44  * the one found in the onion address. */
46 
47  /** (All circuit) Introduction point authentication key. It's also needed on
48  * the rendezvous circuit for the ntor handshake. It's used as the unique key
49  * of the introduction point so it should not be shared between multiple
50  * intro points. */
52 
53  /** (Only client rendezvous circuit) Introduction point encryption public
54  * key. We keep it in the rendezvous identifier for the ntor handshake. */
56 
57  /** (Only rendezvous circuit) Rendezvous cookie sent from the client to the
58  * service with an INTRODUCE1 cell and used by the service in an
59  * RENDEZVOUS1 cell. */
61 
62  /** (Only service rendezvous circuit) The HANDSHAKE_INFO needed in the
63  * RENDEZVOUS1 cell of the service. The construction is as follows:
64  *
65  * SERVER_PK [32 bytes]
66  * AUTH_MAC [32 bytes]
67  */
69 
70  /** (Only client rendezvous circuit) Client ephemeral keypair needed for the
71  * e2e encryption with the service. */
73 
74  /** (Only rendezvous circuit) The NTOR_KEY_SEED needed for key derivation for
75  * the e2e encryption with the client on the circuit. */
77 
78  /** (Only rendezvous circuit) Number of streams associated with this
79  * rendezvous circuit. We track this because there is a check on a maximum
80  * value. */
81  uint64_t num_rdv_streams;
83 
84 /** Client and service side directory connection identifier used for a
85  * directory connection to identify which service is being queried. This is
86  * attached to a dir_connection_t. */
87 typedef struct hs_ident_dir_conn_t {
88  /** The public key used to uniquely identify the service. It is the one found
89  * in the onion address. */
91 
92  /** The blinded public key used to uniquely identify the descriptor that this
93  * directory connection identifier is for. Only used by the service-side code
94  * to fine control descriptor uploads. */
96 
97  /* XXX: Client authorization. */
99 
100 /** Client and service side edge connection identifier used for an edge
101  * connection to identify which service is being queried. This is attached to
102  * a edge_connection_t. */
103 typedef struct hs_ident_edge_conn_t {
104  /** The public key used to uniquely identify the service. It is the one found
105  * in the onion address. */
107 
108  /** The original virtual port that was used by the client to access the onion
109  * service, regardless of the internal port forwarding that might have
110  * happened on the service-side. */
112  /* XXX: Client authorization. */
114 
115 /* Circuit identifier API. */
117  const ed25519_public_key_t *identity_pk);
119 #define hs_ident_circuit_free(id) \
120  FREE_AND_NULL(hs_ident_circuit_t, hs_ident_circuit_free_, (id))
122 
123 /* Directory connection identifier API. */
126 #define hs_ident_dir_conn_free(id) \
127  FREE_AND_NULL(hs_ident_dir_conn_t, hs_ident_dir_conn_free_, (id))
128 void hs_ident_dir_conn_init(const ed25519_public_key_t *identity_pk,
129  const ed25519_public_key_t *blinded_pk,
130  hs_ident_dir_conn_t *ident);
131 
132 /* Edge connection identifier API. */
134  const ed25519_public_key_t *identity_pk);
136 #define hs_ident_edge_conn_free(id) \
137  FREE_AND_NULL(hs_ident_edge_conn_t, hs_ident_edge_conn_free_, (id))
138 
139 /* Validators */
141 
142 #endif /* !defined(TOR_HS_IDENT_H) */
Header for crypto_ed25519.c.
#define DIGEST256_LEN
Definition: digest_sizes.h:23
Header file containing common data for the whole HS subsystem.
void hs_ident_edge_conn_free_(hs_ident_edge_conn_t *ident)
Definition: hs_ident.c:93
#define HS_REND_COOKIE_LEN
Definition: hs_ident.h:30
hs_ident_circuit_type_t
Definition: hs_ident.h:33
void hs_ident_dir_conn_free_(hs_ident_dir_conn_t *ident)
Definition: hs_ident.c:56
hs_ident_circuit_t * hs_ident_circuit_dup(const hs_ident_circuit_t *src)
Definition: hs_ident.c:37
hs_ident_dir_conn_t * hs_ident_dir_conn_dup(const hs_ident_dir_conn_t *src)
Definition: hs_ident.c:47
void hs_ident_circuit_free_(hs_ident_circuit_t *ident)
Definition: hs_ident.c:25
hs_ident_edge_conn_t * hs_ident_edge_conn_new(const ed25519_public_key_t *identity_pk)
Definition: hs_ident.c:84
void hs_ident_dir_conn_init(const ed25519_public_key_t *identity_pk, const ed25519_public_key_t *blinded_pk, hs_ident_dir_conn_t *ident)
Definition: hs_ident.c:69
hs_ident_circuit_t * hs_ident_circuit_new(const ed25519_public_key_t *identity_pk)
Definition: hs_ident.c:16
int hs_ident_intro_circ_is_valid(const hs_ident_circuit_t *ident)
Definition: hs_ident.c:104
uint8_t rendezvous_cookie[HS_REND_COOKIE_LEN]
Definition: hs_ident.h:60
ed25519_public_key_t intro_auth_pk
Definition: hs_ident.h:51
curve25519_keypair_t rendezvous_client_kp
Definition: hs_ident.h:72
curve25519_public_key_t intro_enc_pk
Definition: hs_ident.h:55
uint8_t rendezvous_ntor_key_seed[DIGEST256_LEN]
Definition: hs_ident.h:76
ed25519_public_key_t identity_pk
Definition: hs_ident.h:45
uint64_t num_rdv_streams
Definition: hs_ident.h:81
uint8_t rendezvous_handshake_info[CURVE25519_PUBKEY_LEN+DIGEST256_LEN]
Definition: hs_ident.h:68
ed25519_public_key_t blinded_pk
Definition: hs_ident.h:95
ed25519_public_key_t identity_pk
Definition: hs_ident.h:90
ed25519_public_key_t identity_pk
Definition: hs_ident.h:106
uint16_t orig_virtual_port
Definition: hs_ident.h:111
#define CURVE25519_PUBKEY_LEN
Definition: x25519_sizes.h:20