hs_ident.h (6001B)
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 24 #include "lib/crypt_ops/crypto_ed25519.h" 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, 36 } hs_ident_circuit_type_t; 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. */ 45 ed25519_public_key_t identity_pk; 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. */ 51 ed25519_public_key_t intro_auth_pk; 52 53 /** (Only client rendezvous circuit) Introduction point encryption public 54 * key. We keep it in the rendezvous identifier for the ntor handshake. */ 55 curve25519_public_key_t intro_enc_pk; 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. */ 60 uint8_t rendezvous_cookie[HS_REND_COOKIE_LEN]; 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 */ 68 uint8_t rendezvous_handshake_info[CURVE25519_PUBKEY_LEN + DIGEST256_LEN]; 69 70 /** (Only client rendezvous circuit) Client ephemeral keypair needed for the 71 * e2e encryption with the service. */ 72 curve25519_keypair_t rendezvous_client_kp; 73 74 /** (Only rendezvous circuit) The NTOR_KEY_SEED needed for key derivation for 75 * the e2e encryption with the client on the circuit. */ 76 uint8_t rendezvous_ntor_key_seed[DIGEST256_LEN]; 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; 82 } hs_ident_circuit_t; 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. */ 90 ed25519_public_key_t identity_pk; 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. */ 95 ed25519_public_key_t blinded_pk; 96 97 /* XXX: Client authorization. */ 98 } hs_ident_dir_conn_t; 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. */ 106 ed25519_public_key_t identity_pk; 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. */ 111 uint16_t orig_virtual_port; 112 /* XXX: Client authorization. */ 113 } hs_ident_edge_conn_t; 114 115 /* Circuit identifier API. */ 116 hs_ident_circuit_t *hs_ident_circuit_new( 117 const ed25519_public_key_t *identity_pk); 118 void hs_ident_circuit_free_(hs_ident_circuit_t *ident); 119 #define hs_ident_circuit_free(id) \ 120 FREE_AND_NULL(hs_ident_circuit_t, hs_ident_circuit_free_, (id)) 121 hs_ident_circuit_t *hs_ident_circuit_dup(const hs_ident_circuit_t *src); 122 123 /* Directory connection identifier API. */ 124 hs_ident_dir_conn_t *hs_ident_dir_conn_dup(const hs_ident_dir_conn_t *src); 125 void hs_ident_dir_conn_free_(hs_ident_dir_conn_t *ident); 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 hs_ident_dir_conn_t *hs_ident_server_dir_conn_new( 132 const ed25519_public_key_t *blinded_pk); 133 134 /* Edge connection identifier API. */ 135 hs_ident_edge_conn_t *hs_ident_edge_conn_new( 136 const ed25519_public_key_t *identity_pk); 137 void hs_ident_edge_conn_free_(hs_ident_edge_conn_t *ident); 138 #define hs_ident_edge_conn_free(id) \ 139 FREE_AND_NULL(hs_ident_edge_conn_t, hs_ident_edge_conn_free_, (id)) 140 141 /* Validators */ 142 int hs_ident_intro_circ_is_valid(const hs_ident_circuit_t *ident); 143 144 #endif /* !defined(TOR_HS_IDENT_H) */