Line data Source code
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 321 : hs_desc_is_supported_version(uint32_t version)
248 : {
249 321 : if (version < HS_DESC_SUPPORTED_FORMAT_VERSION_MIN ||
250 : version > HS_DESC_SUPPORTED_FORMAT_VERSION_MAX) {
251 3 : 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) */
|
