Tor  0.4.7.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 
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
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,
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. */
103 
104  /** Onion key of the introduction point used to extend to it for the ntor
105  * handshake. */
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. */
112 
113  /** Encryption key for the "ntor" type. */
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]. */
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. */
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;
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;
141 
142 /** Authorized client information located in a descriptor. */
144  /** An identifier that the client will use to identify which auth client
145  * entry it needs to use. */
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];
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. */
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. */
173 
174 /** The superencrypted data section of a descriptor. Obviously the data in
175  * this is in plaintext but encrypted once encoded. */
177  /** This field contains ephemeral x25519 public key which is used by
178  * the encryption scheme in the client authorization. */
180 
181  /** A list of authorized clients. Contains hs_desc_authorized_client_t
182  * objects. */
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 */
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. */
204 
205  /** Signing public key which is used to sign the descriptor. Same public key
206  * as in the signing key certificate. */
208 
209  /** Blinded public key used for this descriptor derived from the master
210  * identity key and generated for a specific replica number. */
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. */
217 
218  /** Decoding only: The b64-decoded superencrypted blob from the descriptor */
220 
221  /** Decoding only: Size of the superencrypted_blob */
224 
225 /** Service descriptor in its decoded form. */
226 typedef struct hs_descriptor_t {
227  /** Contains the plaintext part of the descriptor. */
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. */
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. */
239 
240  /** Subcredentials of a service, used by the client and service to decrypt
241  * the encrypted data. */
244 
245 /** Return true iff the given descriptor format version is supported. */
246 static inline int
248 {
249  if (version < HS_DESC_SUPPORTED_FORMAT_VERSION_MIN ||
251  return 0;
252  }
253  return 1;
254 }
255 
256 /* Public API. */
257 
259 #define hs_descriptor_free(desc) \
260  FREE_AND_NULL(hs_descriptor_t, hs_descriptor_free_, (desc))
262 #define hs_desc_plaintext_data_free(desc) \
263  FREE_AND_NULL(hs_desc_plaintext_data_t, hs_desc_plaintext_data_free_, (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))
269 #define hs_desc_encrypted_data_free(desc) \
270  FREE_AND_NULL(hs_desc_encrypted_data_t, hs_desc_encrypted_data_free_, (desc))
271 
273 
274 MOCK_DECL(int,
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);
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);
294 
297 #define hs_desc_intro_point_free(ip) \
298  FREE_AND_NULL(hs_desc_intro_point_t, hs_desc_intro_point_free_, (ip))
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 
305 
306 void hs_desc_build_authorized_client(const hs_subcredential_t *subcredential,
308  client_auth_pk,
310  auth_ephemeral_sk,
311  const uint8_t *descriptor_cookie,
312  hs_desc_authorized_client_t *client_out);
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);
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 
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) */
#define CIPHER_IV_LEN
Definition: crypto_cipher.h:24
STATIC smartlist_t * decode_link_specifiers(const char *encoded)
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 size_t decrypt_desc_layer(const hs_descriptor_t *desc, const uint8_t *descriptor_cookie, bool is_superencrypted_layer, char **decrypted_out)
STATIC char * encode_link_specifiers(const smartlist_t *specs)
STATIC size_t build_plaintext_padding(const char *plaintext, size_t plaintext_len, uint8_t **padded_out)
STATIC int encrypted_data_length_is_valid(size_t len)
STATIC int cert_is_valid(tor_cert_t *cert, uint8_t type, const char *log_obj_type)
STATIC hs_desc_intro_point_t * decode_introduction_point(const hs_descriptor_t *desc, const char *start)
hs_desc_intro_point_t * hs_desc_intro_point_new(void)
void hs_desc_superencrypted_data_free_contents(hs_desc_superencrypted_data_t *desc)
hs_desc_authorized_client_t * hs_desc_build_fake_authorized_client(void)
#define HS_DESC_CLIENT_ID_LEN
Definition: hs_descriptor.h:58
hs_desc_decode_status_t
Definition: hs_descriptor.h:74
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:69
void hs_desc_plaintext_data_free_(hs_desc_plaintext_data_t *desc)
size_t hs_desc_plaintext_obj_size(const hs_desc_plaintext_data_t *data)
size_t hs_desc_obj_size(const hs_descriptor_t *data)
int hs_desc_decode_superencrypted(const hs_descriptor_t *desc, hs_desc_superencrypted_data_t *desc_out)
int hs_desc_decode_plaintext(const char *encoded, hs_desc_plaintext_data_t *plaintext)
#define HS_DESC_SUPPORTED_FORMAT_VERSION_MAX
Definition: hs_descriptor.h:25
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:23
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)
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)
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)
void hs_desc_superencrypted_data_free_(hs_desc_superencrypted_data_t *desc)
int 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_desc_encrypted_data_free_(hs_desc_encrypted_data_t *desc)
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.
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
unsigned int single_onion_service
smartlist_t * intro_points
unsigned int cross_certified
struct hs_desc_intro_point_t::@16 legacy
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::@16::@17 cert
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.