src/feature/hs/hs_descriptor.h

   1 /* Copyright (c) 2016-2021, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /**
   5  * \file hs_descriptor.h
   6  * \brief Header file for hs_descriptor.c
   7  **/
   8
   9 #ifndef TOR_HS_DESCRIPTOR_H
  10 #define TOR_HS_DESCRIPTOR_H
  11
  12 #include <stdint.h>
  13
  14 #include "core/or/or.h"
  15 #include "trunnel/ed25519_cert.h" /* needed for trunnel */
  16 #include "feature/nodelist/torcert.h"
  17 #include "core/crypto/hs_ntor.h" /* for hs_subcredential_t */
  18
  19 /* Trunnel */
  20 struct link_specifier_t;
  21
  22 /** The earliest descriptor format version we support. */
  23 #define HS_DESC_SUPPORTED_FORMAT_VERSION_MIN 3
  24 /** The latest descriptor format version we support. */
  25 #define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX 3
  26
  27 /** Default lifetime of a descriptor in seconds. The valus is set at 3 hours
  28  * which is 180 minutes or 10800 seconds. */
  29 #define HS_DESC_DEFAULT_LIFETIME (3 * 60 * 60)
  30 /** Maximum lifetime of a descriptor in seconds. The value is set at 12 hours
  31  * which is 720 minutes or 43200 seconds. */
  32 #define HS_DESC_MAX_LIFETIME (12 * 60 * 60)
  33 /** Lifetime of certificate in the descriptor. This defines the lifetime of the
  34  * descriptor signing key and the cross certification cert of that key. It is
  35  * set to 54 hours because a descriptor can be around for 48 hours and because
  36  * consensuses are used after the hour, add an extra 6 hours to give some time
  37  * for the service to stop using it. */
  38 #define HS_DESC_CERT_LIFETIME (54 * 60 * 60)
  39 /** Length of the salt needed for the encrypted section of a descriptor. */
  40 #define HS_DESC_ENCRYPTED_SALT_LEN 16
  41 /** Length of the KDF output value which is the length of the secret key,
  42  * the secret IV and MAC key length which is the length of H() output. */
  43 #define HS_DESC_ENCRYPTED_KDF_OUTPUT_LEN \
  44   CIPHER256_KEY_LEN + CIPHER_IV_LEN + DIGEST256_LEN
  45 /** Pad plaintext of superencrypted data section before encryption so that its
  46  * length is a multiple of this value. */
  47 #define HS_DESC_SUPERENC_PLAINTEXT_PAD_MULTIPLE 10000
  48 /** Maximum length in bytes of a full hidden service descriptor. */
  49 #define HS_DESC_MAX_LEN 50000 /* 50kb max size */
  50
  51 /** Key length for the descriptor symmetric encryption. As specified in the
  52  * protocol, we use AES-256 for the encrypted section of the descriptor. The
  53  * following is the length in bytes and the bit size. */
  54 #define HS_DESC_ENCRYPTED_KEY_LEN CIPHER256_KEY_LEN
  55 #define HS_DESC_ENCRYPTED_BIT_SIZE (HS_DESC_ENCRYPTED_KEY_LEN * 8)
  56
  57 /** Length of each components in the auth client section in the descriptor. */
  58 #define HS_DESC_CLIENT_ID_LEN 8
  59 #define HS_DESC_DESCRIPTOR_COOKIE_LEN 16
  60 #define HS_DESC_COOKIE_KEY_LEN 32
  61 #define HS_DESC_COOKIE_KEY_BIT_SIZE (HS_DESC_COOKIE_KEY_LEN * 8)
  62 #define HS_DESC_ENCRYPED_COOKIE_LEN HS_DESC_DESCRIPTOR_COOKIE_LEN
  63
  64 /** The number of auth client entries in the descriptor must be the multiple
  65  * of this constant. */
  66 #define HS_DESC_AUTH_CLIENT_MULTIPLE 16
  67
  68 /** Type of authentication in the descriptor. */
  69 typedef enum {
  70   HS_DESC_AUTH_ED25519 = 1
  71 } hs_desc_auth_type_t;
  72
  73 /** Error code when decoding a descriptor. */
  74 typedef enum {
  75   /* The configured client authorization for the requested .onion address
  76    * failed to decode the descriptor. */
  77   HS_DESC_DECODE_BAD_CLIENT_AUTH  = -6,
  78
  79   /* The requested .onion address requires a client authorization. */
  80   HS_DESC_DECODE_NEED_CLIENT_AUTH = -5,
  81
  82   /* Error during decryption of the encrypted layer. */
  83   HS_DESC_DECODE_ENCRYPTED_ERROR  = -4,
  84
  85   /* Error during decryption of the super encrypted layer. */
  86   HS_DESC_DECODE_SUPERENC_ERROR   = -3,
  87
  88   /* Error while decoding the plaintext section. */
  89   HS_DESC_DECODE_PLAINTEXT_ERROR  = -2,
  90
  91   /* Generic error. */
  92   HS_DESC_DECODE_GENERIC_ERROR    = -1,
  93
  94   /* Decoding a descriptor was successful. */
  95   HS_DESC_DECODE_OK               =  0,
  96 } hs_desc_decode_status_t;
  97
  98 /** Introduction point information located in a descriptor. */
  99 typedef struct hs_desc_intro_point_t {
 100   /** Link specifier(s) which details how to extend to the relay. This list
 101    * contains link_specifier_t objects. It MUST have at least one. */
 102   smartlist_t *link_specifiers;
 103
 104   /** Onion key of the introduction point used to extend to it for the ntor
 105    * handshake. */
 106   curve25519_public_key_t onion_key;
 107
 108   /** Authentication key used to establish the introduction point circuit and
 109    * cross-certifies the blinded public key for the replica thus signed by
 110    * the blinded key and in turn signs it. */
 111   tor_cert_t *auth_key_cert;
 112
 113   /** Encryption key for the "ntor" type. */
 114   curve25519_public_key_t enc_key;
 115
 116   /** Certificate cross certifying the descriptor signing key by the encryption
 117    * curve25519 key. This certificate contains the signing key and is of type
 118    * CERT_TYPE_CROSS_HS_IP_KEYS [0B]. */
 119   tor_cert_t *enc_key_cert;
 120
 121   /** (Optional): If this introduction point is a legacy one that is version <=
 122    * 0.2.9.x (HSIntro=3), we use this extra key for the intro point to be able
 123    * to relay the cells to the service correctly. */
 124   struct {
 125     /** RSA public key. */
 126     crypto_pk_t *key;
 127
 128     /** Cross certified cert with the descriptor signing key (RSA->Ed). Because
 129      * of the cross certification API, we need to keep the certificate binary
 130      * blob and its length in order to properly encode it after. */
 131     struct {
 132       uint8_t *encoded;
 133       size_t len;
 134     } cert;
 135   } legacy;
 136
 137   /** True iff the introduction point has passed the cross certification. Upon
 138    * decoding an intro point, this must be true. */
 139   unsigned int cross_certified : 1;
 140 } hs_desc_intro_point_t;
 141
 142 /** Authorized client information located in a descriptor. */
 143 typedef struct hs_desc_authorized_client_t {
 144   /** An identifier that the client will use to identify which auth client
 145    * entry it needs to use. */
 146   uint8_t client_id[HS_DESC_CLIENT_ID_LEN];
 147
 148   /** An IV that is used to decrypt the encrypted descriptor cookie. */
 149   uint8_t iv[CIPHER_IV_LEN];
 150
 151   /** An encrypted descriptor cookie that the client needs to decrypt to use
 152    * it to decrypt the descriptor. */
 153   uint8_t encrypted_cookie[HS_DESC_ENCRYPED_COOKIE_LEN];
 154 } hs_desc_authorized_client_t;
 155
 156 /** The encrypted data section of a descriptor. Obviously the data in this is
 157  * in plaintext but encrypted once encoded. */
 158 typedef struct hs_desc_encrypted_data_t {
 159   /** Bitfield of CREATE2 cell supported formats. The only currently supported
 160    * format is ntor. */
 161   unsigned int create2_ntor : 1;
 162
 163   /** A list of authentication types that a client must at least support one
 164    * in order to contact the service. Contains NULL terminated strings. */
 165   smartlist_t *intro_auth_types;
 166
 167   /** Is this descriptor a single onion service? */
 168   unsigned int single_onion_service : 1;
 169
 170   /** A list of intro points. Contains hs_desc_intro_point_t objects. */
 171   smartlist_t *intro_points;
 172 } hs_desc_encrypted_data_t;
 173
 174 /** The superencrypted data section of a descriptor. Obviously the data in
 175  * this is in plaintext but encrypted once encoded. */
 176 typedef struct hs_desc_superencrypted_data_t {
 177   /** This field contains ephemeral x25519 public key which is used by
 178    * the encryption scheme in the client authorization. */
 179   curve25519_public_key_t auth_ephemeral_pubkey;
 180
 181   /** A list of authorized clients. Contains hs_desc_authorized_client_t
 182    * objects. */
 183   smartlist_t *clients;
 184
 185   /** Decoding only: The b64-decoded encrypted blob from the descriptor */
 186   uint8_t *encrypted_blob;
 187
 188   /** Decoding only: Size of the encrypted_blob */
 189   size_t encrypted_blob_size;
 190 } hs_desc_superencrypted_data_t;
 191
 192 /** Plaintext data that is unencrypted information of the descriptor. */
 193 typedef struct hs_desc_plaintext_data_t {
 194   /** Version of the descriptor format. Spec specifies this field as a
 195    * positive integer. */
 196   uint32_t version;
 197
 198   /** The lifetime of the descriptor in seconds. */
 199   uint32_t lifetime_sec;
 200
 201   /** Certificate with the short-term ed22519 descriptor signing key for the
 202    * replica which is signed by the blinded public key for that replica. */
 203   tor_cert_t *signing_key_cert;
 204
 205   /** Signing public key which is used to sign the descriptor. Same public key
 206    * as in the signing key certificate. */
 207   ed25519_public_key_t signing_pubkey;
 208
 209   /** Blinded public key used for this descriptor derived from the master
 210    * identity key and generated for a specific replica number. */
 211   ed25519_public_key_t blinded_pubkey;
 212
 213   /** Revision counter is incremented at each upload, regardless of whether
 214    * the descriptor has changed. This avoids leaking whether the descriptor
 215    * has changed. Spec specifies this as a 8 bytes positive integer. */
 216   uint64_t revision_counter;
 217
 218   /** Decoding only: The b64-decoded superencrypted blob from the descriptor */
 219   uint8_t *superencrypted_blob;
 220
 221   /** Decoding only: Size of the superencrypted_blob */
 222   size_t superencrypted_blob_size;
 223 } hs_desc_plaintext_data_t;
 224
 225 /** Service descriptor in its decoded form. */
 226 typedef struct hs_descriptor_t {
 227   /** Contains the plaintext part of the descriptor. */
 228   hs_desc_plaintext_data_t plaintext_data;
 229
 230   /** The following contains what's in the superencrypted part of the
 231    * descriptor. It's only encrypted in the encoded version of the descriptor
 232    * thus the data contained in that object is in plaintext. */
 233   hs_desc_superencrypted_data_t superencrypted_data;
 234
 235   /** The following contains what's in the encrypted part of the descriptor.
 236    * It's only encrypted in the encoded version of the descriptor thus the
 237    * data contained in that object is in plaintext. */
 238   hs_desc_encrypted_data_t encrypted_data;
 239
 240   /** Subcredentials of a service, used by the client and service to decrypt
 241    * the encrypted data. */
 242   hs_subcredential_t subcredential;
 243 } hs_descriptor_t;
 244
 245 /** Return true iff the given descriptor format version is supported. */
 246 static inline int
 247 hs_desc_is_supported_version(uint32_t version)
 248 {
 249   if (version < HS_DESC_SUPPORTED_FORMAT_VERSION_MIN ||
 250       version > HS_DESC_SUPPORTED_FORMAT_VERSION_MAX) {
 251     return 0;
 252   }
 253   return 1;
 254 }
 255
 256 /* Public API. */
 257
 258 void hs_descriptor_free_(hs_descriptor_t *desc);
 259 #define hs_descriptor_free(desc) \
 260   FREE_AND_NULL(hs_descriptor_t, hs_descriptor_free_, (desc))
 261 void hs_desc_plaintext_data_free_(hs_desc_plaintext_data_t *desc);
 262 #define hs_desc_plaintext_data_free(desc) \
 263   FREE_AND_NULL(hs_desc_plaintext_data_t, hs_desc_plaintext_data_free_, (desc))
 264 void hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc);
 265 #define hs_desc_superencrypted_data_free(desc) \
 266   FREE_AND_NULL(hs_desc_superencrypted_data_t, \
 267                 hs_desc_superencrypted_data_free_, (desc))
 268 void hs_desc_encrypted_data_free_(hs_desc_encrypted_data_t *desc);
 269 #define hs_desc_encrypted_data_free(desc) \
 270   FREE_AND_NULL(hs_desc_encrypted_data_t, hs_desc_encrypted_data_free_, (desc))
 271
 272 void hs_descriptor_clear_intro_points(hs_descriptor_t *desc);
 273
 274 MOCK_DECL(int,
 275           hs_desc_encode_descriptor,(const hs_descriptor_t *desc,
 276                                      const ed25519_keypair_t *signing_kp,
 277                                      const uint8_t *descriptor_cookie,
 278                                      char **encoded_out));
 279
 280 int hs_desc_decode_descriptor(const char *encoded,
 281                               const hs_subcredential_t *subcredential,
 282                               const curve25519_secret_key_t *client_auth_sk,
 283                               hs_descriptor_t **desc_out);
 284 int hs_desc_decode_plaintext(const char *encoded,
 285                              hs_desc_plaintext_data_t *plaintext);
 286 int hs_desc_decode_superencrypted(const hs_descriptor_t *desc,
 287                                  hs_desc_superencrypted_data_t *desc_out);
 288 int hs_desc_decode_encrypted(const hs_descriptor_t *desc,
 289                              const curve25519_secret_key_t *client_auth_sk,
 290                              hs_desc_encrypted_data_t *desc_out);
 291
 292 size_t hs_desc_obj_size(const hs_descriptor_t *data);
 293 size_t hs_desc_plaintext_obj_size(const hs_desc_plaintext_data_t *data);
 294
 295 hs_desc_intro_point_t *hs_desc_intro_point_new(void);
 296 void hs_desc_intro_point_free_(hs_desc_intro_point_t *ip);
 297 #define hs_desc_intro_point_free(ip) \
 298   FREE_AND_NULL(hs_desc_intro_point_t, hs_desc_intro_point_free_, (ip))
 299 void hs_desc_authorized_client_free_(hs_desc_authorized_client_t *client);
 300 #define hs_desc_authorized_client_free(client) \
 301   FREE_AND_NULL(hs_desc_authorized_client_t, \
 302                 hs_desc_authorized_client_free_, (client))
 303
 304 hs_desc_authorized_client_t *hs_desc_build_fake_authorized_client(void);
 305
 306 void hs_desc_build_authorized_client(const hs_subcredential_t *subcredential,
 307                                      const curve25519_public_key_t *
 308                                      client_auth_pk,
 309                                      const curve25519_secret_key_t *
 310                                      auth_ephemeral_sk,
 311                                      const uint8_t *descriptor_cookie,
 312                                      hs_desc_authorized_client_t *client_out);
 313 void hs_desc_plaintext_data_free_contents(hs_desc_plaintext_data_t *desc);
 314 void hs_desc_superencrypted_data_free_contents(
 315                                         hs_desc_superencrypted_data_t *desc);
 316 void hs_desc_encrypted_data_free_contents(hs_desc_encrypted_data_t *desc);
 317
 318 #ifdef HS_DESCRIPTOR_PRIVATE
 319
 320 /* Encoding. */
 321 STATIC char *encode_link_specifiers(const smartlist_t *specs);
 322 STATIC size_t build_plaintext_padding(const char *plaintext,
 323                                       size_t plaintext_len,
 324                                       uint8_t **padded_out);
 325 /* Decoding. */
 326 STATIC smartlist_t *decode_link_specifiers(const char *encoded);
 327 STATIC hs_desc_intro_point_t *decode_introduction_point(
 328                                 const hs_descriptor_t *desc,
 329                                 const char *text);
 330 STATIC int encrypted_data_length_is_valid(size_t len);
 331 STATIC int cert_is_valid(tor_cert_t *cert, uint8_t type,
 332                          const char *log_obj_type);
 333 STATIC int desc_sig_is_valid(const char *b64_sig,
 334                              const ed25519_public_key_t *signing_pubkey,
 335                              const char *encoded_desc, size_t encoded_len);
 336
 337 MOCK_DECL(STATIC size_t, decrypt_desc_layer,(const hs_descriptor_t *desc,
 338                                              const uint8_t *descriptor_cookie,
 339                                              bool is_superencrypted_layer,
 340                                              char **decrypted_out));
 341
 342 #endif /* defined(HS_DESCRIPTOR_PRIVATE) */
 343
 344 #endif /* !defined(TOR_HS_DESCRIPTOR_H) */