Tor  0.4.4.0-alpha-dev
hs_descriptor.h
Go to the documentation of this file.
1 /* Copyright (c) 2016-2020, 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 
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
71 
72 /** Error code when decoding a descriptor. */
73 typedef enum {
74  /* The configured client authorization for the requested .onion address
75  * failed to decode the descriptor. */
76  HS_DESC_DECODE_BAD_CLIENT_AUTH = -6,
77 
78  /* The requested .onion address requires a client authorization. */
79  HS_DESC_DECODE_NEED_CLIENT_AUTH = -5,
80 
81  /* Error during decryption of the encrypted layer. */
82  HS_DESC_DECODE_ENCRYPTED_ERROR = -4,
83 
84  /* Error during decryption of the super encrypted layer. */
85  HS_DESC_DECODE_SUPERENC_ERROR = -3,
86 
87  /* Error while decoding the plaintext section. */
88  HS_DESC_DECODE_PLAINTEXT_ERROR = -2,
89 
90  /* Generic error. */
91  HS_DESC_DECODE_GENERIC_ERROR = -1,
92 
93  /* Decoding a descriptor was successful. */
94  HS_DESC_DECODE_OK = 0,
96 
97 /** Introduction point information located in a descriptor. */
98 typedef struct hs_desc_intro_point_t {
99  /** Link specifier(s) which details how to extend to the relay. This list
100  * contains link_specifier_t objects. It MUST have at least one. */
102 
103  /** Onion key of the introduction point used to extend to it for the ntor
104  * handshake. */
106 
107  /** Authentication key used to establish the introduction point circuit and
108  * cross-certifies the blinded public key for the replica thus signed by
109  * the blinded key and in turn signs it. */
111 
112  /** Encryption key for the "ntor" type. */
114 
115  /** Certificate cross certifying the descriptor signing key by the encryption
116  * curve25519 key. This certificate contains the signing key and is of type
117  * CERT_TYPE_CROSS_HS_IP_KEYS [0B]. */
119 
120  /** (Optional): If this introduction point is a legacy one that is version <=
121  * 0.2.9.x (HSIntro=3), we use this extra key for the intro point to be able
122  * to relay the cells to the service correctly. */
123  struct {
124  /** RSA public key. */
126 
127  /** Cross certified cert with the descriptor signing key (RSA->Ed). Because
128  * of the cross certification API, we need to keep the certificate binary
129  * blob and its length in order to properly encode it after. */
130  struct {
131  uint8_t *encoded;
132  size_t len;
133  } cert;
134  } legacy;
135 
136  /** True iff the introduction point has passed the cross certification. Upon
137  * decoding an intro point, this must be true. */
138  unsigned int cross_certified : 1;
140 
141 /** Authorized client information located in a descriptor. */
143  /** An identifier that the client will use to identify which auth client
144  * entry it needs to use. */
146 
147  /** An IV that is used to decrypt the encrypted descriptor cookie. */
148  uint8_t iv[CIPHER_IV_LEN];
149 
150  /** An encrypted descriptor cookie that the client needs to decrypt to use
151  * it to decrypt the descriptor. */
152  uint8_t encrypted_cookie[HS_DESC_ENCRYPED_COOKIE_LEN];
154 
155 /** The encrypted data section of a descriptor. Obviously the data in this is
156  * in plaintext but encrypted once encoded. */
157 typedef struct hs_desc_encrypted_data_t {
158  /** Bitfield of CREATE2 cell supported formats. The only currently supported
159  * format is ntor. */
160  unsigned int create2_ntor : 1;
161 
162  /** A list of authentication types that a client must at least support one
163  * in order to contact the service. Contains NULL terminated strings. */
165 
166  /** Is this descriptor a single onion service? */
167  unsigned int single_onion_service : 1;
168 
169  /** A list of intro points. Contains hs_desc_intro_point_t objects. */
172 
173 /** The superencrypted data section of a descriptor. Obviously the data in
174  * this is in plaintext but encrypted once encoded. */
176  /** This field contains ephemeral x25519 public key which is used by
177  * the encryption scheme in the client authorization. */
179 
180  /** A list of authorized clients. Contains hs_desc_authorized_client_t
181  * objects. */
183 
184  /** Decoding only: The b64-decoded encrypted blob from the descriptor */
185  uint8_t *encrypted_blob;
186 
187  /** Decoding only: Size of the encrypted_blob */
190 
191 /** Plaintext data that is unencrypted information of the descriptor. */
192 typedef struct hs_desc_plaintext_data_t {
193  /** Version of the descriptor format. Spec specifies this field as a
194  * positive integer. */
195  uint32_t version;
196 
197  /** The lifetime of the descriptor in seconds. */
198  uint32_t lifetime_sec;
199 
200  /** Certificate with the short-term ed22519 descriptor signing key for the
201  * replica which is signed by the blinded public key for that replica. */
203 
204  /** Signing public key which is used to sign the descriptor. Same public key
205  * as in the signing key certificate. */
207 
208  /** Blinded public key used for this descriptor derived from the master
209  * identity key and generated for a specific replica number. */
211 
212  /** Revision counter is incremented at each upload, regardless of whether
213  * the descriptor has changed. This avoids leaking whether the descriptor
214  * has changed. Spec specifies this as a 8 bytes positive integer. */
216 
217  /** Decoding only: The b64-decoded superencrypted blob from the descriptor */
219 
220  /** Decoding only: Size of the superencrypted_blob */
223 
224 /** Service descriptor in its decoded form. */
225 typedef struct hs_descriptor_t {
226  /** Contains the plaintext part of the descriptor. */
228 
229  /** The following contains what's in the superencrypted part of the
230  * descriptor. It's only encrypted in the encoded version of the descriptor
231  * thus the data contained in that object is in plaintext. */
233 
234  /** The following contains what's in the encrypted part of the descriptor.
235  * It's only encrypted in the encoded version of the descriptor thus the
236  * data contained in that object is in plaintext. */
238 
239  /** Subcredentials of a service, used by the client and service to decrypt
240  * the encrypted data. */
243 
244 /** Return true iff the given descriptor format version is supported. */
245 static inline int
247 {
248  if (version < HS_DESC_SUPPORTED_FORMAT_VERSION_MIN ||
250  return 0;
251  }
252  return 1;
253 }
254 
255 /* Public API. */
256 
258 #define hs_descriptor_free(desc) \
259  FREE_AND_NULL(hs_descriptor_t, hs_descriptor_free_, (desc))
261 #define hs_desc_plaintext_data_free(desc) \
262  FREE_AND_NULL(hs_desc_plaintext_data_t, hs_desc_plaintext_data_free_, (desc))
264 #define hs_desc_superencrypted_data_free(desc) \
265  FREE_AND_NULL(hs_desc_superencrypted_data_t, \
266  hs_desc_superencrypted_data_free_, (desc))
268 #define hs_desc_encrypted_data_free(desc) \
269  FREE_AND_NULL(hs_desc_encrypted_data_t, hs_desc_encrypted_data_free_, (desc))
270 
272 
273 MOCK_DECL(int,
275  const ed25519_keypair_t *signing_kp,
276  const uint8_t *descriptor_cookie,
277  char **encoded_out));
278 
279 int hs_desc_decode_descriptor(const char *encoded,
280  const uint8_t *subcredential,
281  const curve25519_secret_key_t *client_auth_sk,
282  hs_descriptor_t **desc_out);
283 int hs_desc_decode_plaintext(const char *encoded,
284  hs_desc_plaintext_data_t *plaintext);
288  const curve25519_secret_key_t *client_auth_sk,
289  hs_desc_encrypted_data_t *desc_out);
290 
291 size_t hs_desc_obj_size(const hs_descriptor_t *data);
293 
296 #define hs_desc_intro_point_free(ip) \
297  FREE_AND_NULL(hs_desc_intro_point_t, hs_desc_intro_point_free_, (ip))
299 #define hs_desc_authorized_client_free(client) \
300  FREE_AND_NULL(hs_desc_authorized_client_t, \
301  hs_desc_authorized_client_free_, (client))
302 
304 
305 void hs_desc_build_authorized_client(const uint8_t *subcredential,
307  client_auth_pk,
309  auth_ephemeral_sk,
310  const uint8_t *descriptor_cookie,
311  hs_desc_authorized_client_t *client_out);
316 
317 #ifdef HS_DESCRIPTOR_PRIVATE
318 
319 /* Encoding. */
320 STATIC char *encode_link_specifiers(const smartlist_t *specs);
321 STATIC size_t build_plaintext_padding(const char *plaintext,
322  size_t plaintext_len,
323  uint8_t **padded_out);
324 /* Decoding. */
325 STATIC smartlist_t *decode_link_specifiers(const char *encoded);
327  const hs_descriptor_t *desc,
328  const char *text);
329 STATIC int encrypted_data_length_is_valid(size_t len);
330 STATIC int cert_is_valid(tor_cert_t *cert, uint8_t type,
331  const char *log_obj_type);
332 STATIC int desc_sig_is_valid(const char *b64_sig,
333  const ed25519_public_key_t *signing_pubkey,
334  const char *encoded_desc, size_t encoded_len);
335 
337  const uint8_t *descriptor_cookie,
338  bool is_superencrypted_layer,
339  char **decrypted_out));
340 
341 #endif /* defined(HS_DESCRIPTOR_PRIVATE) */
342 
343 #endif /* !defined(TOR_HS_DESCRIPTOR_H) */
uint8_t client_id[HS_DESC_CLIENT_ID_LEN]
void hs_desc_superencrypted_data_free_contents(hs_desc_superencrypted_data_t *desc)
static int hs_desc_is_supported_version(uint32_t version)
hs_desc_superencrypted_data_t superencrypted_data
int hs_desc_decode_descriptor(const char *encoded, const uint8_t *subcredential, const curve25519_secret_key_t *client_auth_sk, hs_descriptor_t **desc_out)
hs_desc_encrypted_data_t encrypted_data
ed25519_public_key_t signing_pubkey
void hs_desc_encrypted_data_free_(hs_desc_encrypted_data_t *desc)
struct hs_desc_intro_point_t::@16 legacy
uint8_t subcredential[DIGEST256_LEN]
size_t hs_desc_plaintext_obj_size(const hs_desc_plaintext_data_t *data)
unsigned int single_onion_service
STATIC size_t build_plaintext_padding(const char *plaintext, size_t plaintext_len, uint8_t **padded_out)
smartlist_t * intro_auth_types
tor_cert_t * enc_key_cert
void hs_desc_authorized_client_free_(hs_desc_authorized_client_t *client)
unsigned int cross_certified
ed25519_public_key_t blinded_pubkey
hs_desc_authorized_client_t * hs_desc_build_fake_authorized_client(void)
#define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX
Definition: hs_descriptor.h:24
#define STATIC
Definition: testsupport.h:32
void hs_desc_build_authorized_client(const uint8_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)
#define CIPHER_IV_LEN
Definition: crypto_cipher.h:24
#define DIGEST256_LEN
Definition: digest_sizes.h:23
uint8_t encrypted_cookie[HS_DESC_ENCRYPED_COOKIE_LEN]
void hs_desc_encrypted_data_free_contents(hs_desc_encrypted_data_t *desc)
hs_desc_plaintext_data_t plaintext_data
void hs_desc_intro_point_free_(hs_desc_intro_point_t *ip)
STATIC size_t decrypt_desc_layer(const hs_descriptor_t *desc, const uint8_t *descriptor_cookie, bool is_superencrypted_layer, char **decrypted_out)
int hs_desc_decode_encrypted(const hs_descriptor_t *desc, const curve25519_secret_key_t *client_auth_sk, hs_desc_encrypted_data_t *desc_out)
STATIC smartlist_t * decode_link_specifiers(const char *encoded)
curve25519_public_key_t onion_key
void hs_descriptor_clear_intro_points(hs_descriptor_t *desc)
uint8_t iv[CIPHER_IV_LEN]
tor_cert_t * signing_key_cert
Master header file for Tor-specific functionality.
struct hs_desc_intro_point_t::@16::@17 cert
hs_desc_intro_point_t * hs_desc_intro_point_new(void)
STATIC hs_desc_intro_point_t * decode_introduction_point(const hs_descriptor_t *desc, const char *start)
hs_desc_auth_type_t
Definition: hs_descriptor.h:68
void hs_desc_plaintext_data_free_contents(hs_desc_plaintext_data_t *desc)
#define HS_DESC_SUPPORTED_FORMAT_VERSION_MIN
Definition: hs_descriptor.h:22
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)
curve25519_public_key_t enc_key
void hs_desc_plaintext_data_free_(hs_desc_plaintext_data_t *desc)
smartlist_t * link_specifiers
STATIC int cert_is_valid(tor_cert_t *cert, uint8_t type, const char *log_obj_type)
size_t hs_desc_obj_size(const hs_descriptor_t *data)
smartlist_t * intro_points
STATIC int encrypted_data_length_is_valid(size_t len)
curve25519_public_key_t auth_ephemeral_pubkey
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
Header for torcert.c.
#define HS_DESC_CLIENT_ID_LEN
Definition: hs_descriptor.h:57
void hs_descriptor_free_(hs_descriptor_t *desc)
int hs_desc_decode_superencrypted(const hs_descriptor_t *desc, hs_desc_superencrypted_data_t *desc_out)
STATIC char * encode_link_specifiers(const smartlist_t *specs)
int hs_desc_decode_plaintext(const char *encoded, hs_desc_plaintext_data_t *plaintext)
int hs_desc_encode_descriptor(const hs_descriptor_t *desc, const ed25519_keypair_t *signing_kp, const uint8_t *descriptor_cookie, char **encoded_out)
void hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc)
hs_desc_decode_status_t
Definition: hs_descriptor.h:73
tor_cert_t * auth_key_cert