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