src/or/hs_ident.h

   1 /* Copyright (c) 2017, 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 subsytem.
   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 "crypto.h"
  25 #include "crypto_ed25519.h"
  26
  27 #include "hs_common.h"
  28
  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
  32
  33 /* Type of circuit an hs_ident_t object is associated with. */
  34 typedef enum {
  35   HS_IDENT_CIRCUIT_INTRO      = 1,
  36   HS_IDENT_CIRCUIT_RENDEZVOUS = 2,
  37 } hs_ident_circuit_type_t;
  38
  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;
  47
  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;
  54
  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
  58    * intro points. */
  59   ed25519_public_key_t intro_auth_pk;
  60
  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;
  64
  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];
  69
  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]
  73    *    AUTH_MAC    [32 bytes]
  74    */
  75   uint8_t rendezvous_handshake_info[CURVE25519_PUBKEY_LEN + DIGEST256_LEN];
  76
  77   /* (Only client rendezvous circuit) Client ephemeral keypair needed for the
  78    * e2e encryption with the service. */
  79   curve25519_keypair_t rendezvous_client_kp;
  80
  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];
  84
  85   /* (Only rendezvous circuit) Number of streams associated with this
  86    * rendezvous circuit. We track this because there is a check on a maximum
  87    * value. */
  88   uint64_t num_rdv_streams;
  89 } hs_ident_circuit_t;
  90
  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;
  98
  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;
 103
 104   /* XXX: Client authorization. */
 105 } hs_ident_dir_conn_t;
 106
 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;
 114
 115   /* XXX: Client authorization. */
 116 } hs_ident_edge_conn_t;
 117
 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);
 124
 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);
 131
 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);
 136
 137 /* Validators */
 138 int hs_ident_intro_circ_is_valid(const hs_ident_circuit_t *ident);
 139
 140 #endif /* !defined(TOR_HS_IDENT_H) */
 141