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