Tor 0.4.9.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
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. */
33typedef 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. */
42typedef 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. */
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. */
87typedef 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. */
103typedef 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))
128void 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
hs_ident_dir_conn_t * hs_ident_dir_conn_dup(const hs_ident_dir_conn_t *src)
Definition: hs_ident.c:47
#define HS_REND_COOKIE_LEN
Definition: hs_ident.h:30
hs_ident_circuit_t * hs_ident_circuit_new(const ed25519_public_key_t *identity_pk)
Definition: hs_ident.c:16
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
void hs_ident_circuit_free_(hs_ident_circuit_t *ident)
Definition: hs_ident.c:25
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_edge_conn_t * hs_ident_edge_conn_new(const ed25519_public_key_t *identity_pk)
Definition: hs_ident.c:84
hs_ident_circuit_t * hs_ident_circuit_dup(const hs_ident_circuit_t *src)
Definition: hs_ident.c:37
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