src/or/hs_descriptor.h

   1 /* Copyright (c) 2016-2017, 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 "or.h"
  15 #include "address.h"
  16 #include "container.h"
  17 #include "crypto.h"
  18 #include "crypto_ed25519.h"
  19 #include "torcert.h"
  20
  21 /* Trunnel */
  22 struct link_specifier_t;
  23
  24 /* The earliest descriptor format version we support. */
  25 #define HS_DESC_SUPPORTED_FORMAT_VERSION_MIN 3
  26 /* The latest descriptor format version we support. */
  27 #define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX 3
  28
  29 /* Default lifetime of a descriptor in seconds. The valus is set at 3 hours
  30  * which is 180 minutes or 10800 seconds. */
  31 #define HS_DESC_DEFAULT_LIFETIME (3 * 60 * 60)
  32 /* Maximum lifetime of a descriptor in seconds. The value is set at 12 hours
  33  * which is 720 minutes or 43200 seconds. */
  34 #define HS_DESC_MAX_LIFETIME (12 * 60 * 60)
  35 /* Lifetime of certificate in the descriptor. This defines the lifetime of the
  36  * descriptor signing key and the cross certification cert of that key. It is
  37  * set to 54 hours because a descriptor can be around for 48 hours and because
  38  * consensuses are used after the hour, add an extra 6 hours to give some time
  39  * for the service to stop using it. */
  40 #define HS_DESC_CERT_LIFETIME (54 * 60 * 60)
  41 /* Length of the salt needed for the encrypted section of a descriptor. */
  42 #define HS_DESC_ENCRYPTED_SALT_LEN 16
  43 /* Length of the secret input needed for the KDF construction which derives
  44  * the encryption key for the encrypted data section of the descriptor. This
  45  * adds up to 68 bytes being the blinded key, hashed subcredential and
  46  * revision counter. */
  47 #define HS_DESC_ENCRYPTED_SECRET_INPUT_LEN \
  48   ED25519_PUBKEY_LEN + DIGEST256_LEN + sizeof(uint64_t)
  49 /* Length of the KDF output value which is the length of the secret key,
  50  * the secret IV and MAC key length which is the length of H() output. */
  51 #define HS_DESC_ENCRYPTED_KDF_OUTPUT_LEN \
  52   CIPHER256_KEY_LEN + CIPHER_IV_LEN + DIGEST256_LEN
  53 /* Pad plaintext of superencrypted data section before encryption so that its
  54  * length is a multiple of this value. */
  55 #define HS_DESC_SUPERENC_PLAINTEXT_PAD_MULTIPLE 10000
  56 /* Maximum length in bytes of a full hidden service descriptor. */
  57 #define HS_DESC_MAX_LEN 50000 /* 50kb max size */
  58
  59 /* Key length for the descriptor symmetric encryption. As specified in the
  60  * protocol, we use AES-256 for the encrypted section of the descriptor. The
  61  * following is the length in bytes and the bit size. */
  62 #define HS_DESC_ENCRYPTED_KEY_LEN CIPHER256_KEY_LEN
  63 #define HS_DESC_ENCRYPTED_BIT_SIZE (HS_DESC_ENCRYPTED_KEY_LEN * 8)
  64
  65 /* Type of authentication in the descriptor. */
  66 typedef enum {
  67   HS_DESC_AUTH_ED25519 = 1
  68 } hs_desc_auth_type_t;
  69
  70 /* Link specifier object that contains information on how to extend to the
  71  * relay that is the address, port and handshake type. */
  72 typedef struct hs_desc_link_specifier_t {
  73   /* Indicate the type of link specifier. See trunnel ed25519_cert
  74    * specification. */
  75   uint8_t type;
  76
  77   /* It must be one of these types, can't be more than one. */
  78   union {
  79     /* IP address and port of the relay use to extend. */
  80     tor_addr_port_t ap;
  81     /* Legacy identity. A 20-byte SHA1 identity fingerprint. */
  82     uint8_t legacy_id[DIGEST_LEN];
  83     /* ed25519 identity. A 32-byte key. */
  84     uint8_t ed25519_id[ED25519_PUBKEY_LEN];
  85   } u;
  86 } hs_desc_link_specifier_t;
  87
  88 /* Introduction point information located in a descriptor. */
  89 typedef struct hs_desc_intro_point_t {
  90   /* Link specifier(s) which details how to extend to the relay. This list
  91    * contains hs_desc_link_specifier_t object. It MUST have at least one. */
  92   smartlist_t *link_specifiers;
  93
  94   /* Onion key of the introduction point used to extend to it for the ntor
  95    * handshake. */
  96   curve25519_public_key_t onion_key;
  97
  98   /* Authentication key used to establish the introduction point circuit and
  99    * cross-certifies the blinded public key for the replica thus signed by
 100    * the blinded key and in turn signs it. */
 101   tor_cert_t *auth_key_cert;
 102
 103   /* Encryption key for the "ntor" type. */
 104   curve25519_public_key_t enc_key;
 105
 106   /* Certificate cross certifying the descriptor signing key by the encryption
 107    * curve25519 key. This certificate contains the signing key and is of type
 108    * CERT_TYPE_CROSS_HS_IP_KEYS [0B]. */
 109   tor_cert_t *enc_key_cert;
 110
 111   /* (Optional): If this introduction point is a legacy one that is version <=
 112    * 0.2.9.x (HSIntro=3), we use this extra key for the intro point to be able
 113    * to relay the cells to the service correctly. */
 114   struct {
 115     /* RSA public key. */
 116     crypto_pk_t *key;
 117
 118     /* Cross certified cert with the descriptor signing key (RSA->Ed). Because
 119      * of the cross certification API, we need to keep the certificate binary
 120      * blob and its length in order to properly encode it after. */
 121     struct {
 122       uint8_t *encoded;
 123       size_t len;
 124     } cert;
 125   } legacy;
 126
 127   /* True iff the introduction point has passed the cross certification. Upon
 128    * decoding an intro point, this must be true. */
 129   unsigned int cross_certified : 1;
 130 } hs_desc_intro_point_t;
 131
 132 /* The encrypted data section of a descriptor. Obviously the data in this is
 133  * in plaintext but encrypted once encoded. */
 134 typedef struct hs_desc_encrypted_data_t {
 135   /* Bitfield of CREATE2 cell supported formats. The only currently supported
 136    * format is ntor. */
 137   unsigned int create2_ntor : 1;
 138
 139   /* A list of authentication types that a client must at least support one
 140    * in order to contact the service. Contains NULL terminated strings. */
 141   smartlist_t *intro_auth_types;
 142
 143   /* Is this descriptor a single onion service? */
 144   unsigned int single_onion_service : 1;
 145
 146   /* A list of intro points. Contains hs_desc_intro_point_t objects. */
 147   smartlist_t *intro_points;
 148 } hs_desc_encrypted_data_t;
 149
 150 /* Plaintext data that is unencrypted information of the descriptor. */
 151 typedef struct hs_desc_plaintext_data_t {
 152   /* Version of the descriptor format. Spec specifies this field as a
 153    * positive integer. */
 154   uint32_t version;
 155
 156   /* The lifetime of the descriptor in seconds. */
 157   uint32_t lifetime_sec;
 158
 159   /* Certificate with the short-term ed22519 descriptor signing key for the
 160    * replica which is signed by the blinded public key for that replica. */
 161   tor_cert_t *signing_key_cert;
 162
 163   /* Signing public key which is used to sign the descriptor. Same public key
 164    * as in the signing key certificate. */
 165   ed25519_public_key_t signing_pubkey;
 166
 167   /* Blinded public key used for this descriptor derived from the master
 168    * identity key and generated for a specific replica number. */
 169   ed25519_public_key_t blinded_pubkey;
 170
 171   /* Revision counter is incremented at each upload, regardless of whether
 172    * the descriptor has changed. This avoids leaking whether the descriptor
 173    * has changed. Spec specifies this as a 8 bytes positive integer. */
 174   uint64_t revision_counter;
 175
 176   /* Decoding only: The b64-decoded superencrypted blob from the descriptor */
 177   uint8_t *superencrypted_blob;
 178
 179   /* Decoding only: Size of the superencrypted_blob */
 180   size_t superencrypted_blob_size;
 181 } hs_desc_plaintext_data_t;
 182
 183 /* Service descriptor in its decoded form. */
 184 typedef struct hs_descriptor_t {
 185   /* Contains the plaintext part of the descriptor. */
 186   hs_desc_plaintext_data_t plaintext_data;
 187
 188   /* The following contains what's in the encrypted part of the descriptor.
 189    * It's only encrypted in the encoded version of the descriptor thus the
 190    * data contained in that object is in plaintext. */
 191   hs_desc_encrypted_data_t encrypted_data;
 192
 193   /* Subcredentials of a service, used by the client and service to decrypt
 194    * the encrypted data. */
 195   uint8_t subcredential[DIGEST256_LEN];
 196 } hs_descriptor_t;
 197
 198 /* Return true iff the given descriptor format version is supported. */
 199 static inline int
 200 hs_desc_is_supported_version(uint32_t version)
 201 {
 202   if (version < HS_DESC_SUPPORTED_FORMAT_VERSION_MIN ||
 203       version > HS_DESC_SUPPORTED_FORMAT_VERSION_MAX) {
 204     return 0;
 205   }
 206   return 1;
 207 }
 208
 209 /* Public API. */
 210
 211 void hs_descriptor_free(hs_descriptor_t *desc);
 212 void hs_desc_plaintext_data_free(hs_desc_plaintext_data_t *desc);
 213 void hs_desc_encrypted_data_free(hs_desc_encrypted_data_t *desc);
 214
 215 void hs_desc_link_specifier_free(hs_desc_link_specifier_t *ls);
 216 hs_desc_link_specifier_t *hs_desc_link_specifier_new(
 217                                   const extend_info_t *info, uint8_t type);
 218 void hs_descriptor_clear_intro_points(hs_descriptor_t *desc);
 219
 220 MOCK_DECL(int,
 221           hs_desc_encode_descriptor,(const hs_descriptor_t *desc,
 222                                      const ed25519_keypair_t *signing_kp,
 223                                      char **encoded_out));
 224
 225 int hs_desc_decode_descriptor(const char *encoded,
 226                               const uint8_t *subcredential,
 227                               hs_descriptor_t **desc_out);
 228 int hs_desc_decode_plaintext(const char *encoded,
 229                              hs_desc_plaintext_data_t *plaintext);
 230 int hs_desc_decode_encrypted(const hs_descriptor_t *desc,
 231                              hs_desc_encrypted_data_t *desc_out);
 232
 233 size_t hs_desc_obj_size(const hs_descriptor_t *data);
 234 size_t hs_desc_plaintext_obj_size(const hs_desc_plaintext_data_t *data);
 235
 236 hs_desc_intro_point_t *hs_desc_intro_point_new(void);
 237 void hs_desc_intro_point_free(hs_desc_intro_point_t *ip);
 238
 239 link_specifier_t *hs_desc_lspec_to_trunnel(
 240                                    const hs_desc_link_specifier_t *spec);
 241
 242 #ifdef HS_DESCRIPTOR_PRIVATE
 243
 244 /* Encoding. */
 245 STATIC char *encode_link_specifiers(const smartlist_t *specs);
 246 STATIC size_t build_plaintext_padding(const char *plaintext,
 247                                       size_t plaintext_len,
 248                                       uint8_t **padded_out);
 249 /* Decoding. */
 250 STATIC smartlist_t *decode_link_specifiers(const char *encoded);
 251 STATIC hs_desc_intro_point_t *decode_introduction_point(
 252                                 const hs_descriptor_t *desc,
 253                                 const char *text);
 254 STATIC int encrypted_data_length_is_valid(size_t len);
 255 STATIC int cert_is_valid(tor_cert_t *cert, uint8_t type,
 256                          const char *log_obj_type);
 257 STATIC int desc_sig_is_valid(const char *b64_sig,
 258                              const ed25519_public_key_t *signing_pubkey,
 259                              const char *encoded_desc, size_t encoded_len);
 260 STATIC size_t decode_superencrypted(const char *message, size_t message_len,
 261                                    uint8_t **encrypted_out);
 262 STATIC void desc_plaintext_data_free_contents(hs_desc_plaintext_data_t *desc);
 263
 264 MOCK_DECL(STATIC size_t, decrypt_desc_layer,(const hs_descriptor_t *desc,
 265                                              const uint8_t *encrypted_blob,
 266                                              size_t encrypted_blob_size,
 267                                              int is_superencrypted_layer,
 268                                              char **decrypted_out));
 269
 270 #endif /* defined(HS_DESCRIPTOR_PRIVATE) */
 271
 272 #endif /* !defined(TOR_HS_DESCRIPTOR_H) */
 273