hs_ident.h 6.2 KB

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