1 /* Copyright (c) 2017, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
6 * \brief Header file containing circuit and connection identifier data for
7 * the whole HS subsytem.
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
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.
21 #ifndef TOR_HS_IDENT_H
22 #define TOR_HS_IDENT_H
25 #include "crypto_ed25519.h"
27 #include "hs_common.h"
29 /* Length of the rendezvous cookie that is used to connect circuits at the
30 * rendezvous point. */
31 #define HS_REND_COOKIE_LEN DIGEST_LEN
33 /* Type of circuit an hs_ident_t object is associated with. */
35 HS_IDENT_CIRCUIT_INTRO
= 1,
36 HS_IDENT_CIRCUIT_RENDEZVOUS
= 2,
37 } hs_ident_circuit_type_t
;
39 /* Client and service side circuit identifier that is used for hidden service
40 * circuit establishment. Not all fields contain data, it depends on the
41 * circuit purpose. This is attached to an origin_circuit_t. All fields are
42 * used by both client and service. */
43 typedef struct hs_ident_circuit_t
{
44 /* (All circuit) The public key used to uniquely identify the service. It is
45 * the one found in the onion address. */
46 ed25519_public_key_t identity_pk
;
48 /* (All circuit) The type of circuit this identifier is attached to.
49 * Accessors of the fields in this object assert non fatal on this circuit
50 * type. In other words, if a rendezvous field is being accessed, the
51 * circuit type MUST BE of type HS_IDENT_CIRCUIT_RENDEZVOUS. This value is
52 * set when an object is initialized in its constructor. */
53 hs_ident_circuit_type_t circuit_type
;
55 /* (All circuit) Introduction point authentication key. It's also needed on
56 * the rendezvous circuit for the ntor handshake. It's used as the unique key
57 * of the introduction point so it should not be shared between multiple
59 ed25519_public_key_t intro_auth_pk
;
61 /* (Only client rendezvous circuit) Introduction point encryption public
62 * key. We keep it in the rendezvous identifier for the ntor handshake. */
63 curve25519_public_key_t intro_enc_pk
;
65 /* (Only rendezvous circuit) Rendezvous cookie sent from the client to the
66 * service with an INTRODUCE1 cell and used by the service in an
67 * RENDEZVOUS1 cell. */
68 uint8_t rendezvous_cookie
[HS_REND_COOKIE_LEN
];
70 /* (Only service rendezvous circuit) The HANDSHAKE_INFO needed in the
71 * RENDEZVOUS1 cell of the service. The construction is as follows:
72 * SERVER_PK [32 bytes]
75 uint8_t rendezvous_handshake_info
[CURVE25519_PUBKEY_LEN
+ DIGEST256_LEN
];
77 /* (Only client rendezvous circuit) Client ephemeral keypair needed for the
78 * e2e encryption with the service. */
79 curve25519_keypair_t rendezvous_client_kp
;
81 /* (Only rendezvous circuit) The NTOR_KEY_SEED needed for key derivation for
82 * the e2e encryption with the client on the circuit. */
83 uint8_t rendezvous_ntor_key_seed
[DIGEST256_LEN
];
85 /* (Only rendezvous circuit) Number of streams associated with this
86 * rendezvous circuit. We track this because there is a check on a maximum
88 uint64_t num_rdv_streams
;
91 /* Client and service side directory connection identifier used for a
92 * directory connection to identify which service is being queried. This is
93 * attached to a dir_connection_t. */
94 typedef struct hs_ident_dir_conn_t
{
95 /* The public key used to uniquely identify the service. It is the one found
96 * in the onion address. */
97 ed25519_public_key_t identity_pk
;
99 /* The blinded public key used to uniquely identify the descriptor that this
100 * directory connection identifier is for. Only used by the service-side code
101 * to fine control descriptor uploads. */
102 ed25519_public_key_t blinded_pk
;
104 /* XXX: Client authorization. */
105 } hs_ident_dir_conn_t
;
107 /* Client and service side edge connection identifier used for an edge
108 * connection to identify which service is being queried. This is attached to
109 * a edge_connection_t. */
110 typedef struct hs_ident_edge_conn_t
{
111 /* The public key used to uniquely identify the service. It is the one found
112 * in the onion address. */
113 ed25519_public_key_t identity_pk
;
115 /* XXX: Client authorization. */
116 } hs_ident_edge_conn_t
;
118 /* Circuit identifier API. */
119 hs_ident_circuit_t
*hs_ident_circuit_new(
120 const ed25519_public_key_t
*identity_pk
,
121 hs_ident_circuit_type_t circuit_type
);
122 void hs_ident_circuit_free(hs_ident_circuit_t
*ident
);
123 hs_ident_circuit_t
*hs_ident_circuit_dup(const hs_ident_circuit_t
*src
);
125 /* Directory connection identifier API. */
126 hs_ident_dir_conn_t
*hs_ident_dir_conn_dup(const hs_ident_dir_conn_t
*src
);
127 void hs_ident_dir_conn_free(hs_ident_dir_conn_t
*ident
);
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
);
132 /* Edge connection identifier API. */
133 hs_ident_edge_conn_t
*hs_ident_edge_conn_new(
134 const ed25519_public_key_t
*identity_pk
);
135 void hs_ident_edge_conn_free(hs_ident_edge_conn_t
*ident
);
138 int hs_ident_intro_circ_is_valid(const hs_ident_circuit_t
*ident
);
140 #endif /* !defined(TOR_HS_IDENT_H) */