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