Tor  0.4.5.0-alpha-dev
parsecommon.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 parsecommon.h
6  * \brief Header file for parsecommon.c
7  **/
8 
9 #ifndef TOR_PARSECOMMON_H
10 #define TOR_PARSECOMMON_H
11 
12 #include <stddef.h>
13 
14 struct smartlist_t;
15 struct crypto_pk_t;
16 struct memarea_t;
17 
18 /** Enumeration of possible token types. The ones starting with K_ correspond
19 * to directory 'keywords'. A_ is for an annotation, R or C is related to
20 * hidden services, ERR_ is an error in the tokenizing process, EOF_ is an
21 * end-of-file marker, and NIL_ is used to encode not-a-token.
22 */
23 typedef enum {
24  K_ACCEPT = 0,
25  K_ACCEPT6,
26  K_DIRECTORY_SIGNATURE,
27  K_RECOMMENDED_SOFTWARE,
28  K_REJECT,
29  K_REJECT6,
30  K_ROUTER,
31  K_SIGNED_DIRECTORY,
32  K_SIGNING_KEY,
33  K_ONION_KEY,
34  K_ONION_KEY_NTOR,
35  K_ROUTER_SIGNATURE,
36  K_PUBLISHED,
37  K_RUNNING_ROUTERS,
38  K_ROUTER_STATUS,
39  K_PLATFORM,
40  K_PROTO,
41  K_OPT,
42  K_BANDWIDTH,
43  K_CONTACT,
44  K_NETWORK_STATUS,
45  K_UPTIME,
46  K_DIR_SIGNING_KEY,
47  K_FAMILY,
48  K_FINGERPRINT,
49  K_HIBERNATING,
50  K_READ_HISTORY,
51  K_WRITE_HISTORY,
52  K_NETWORK_STATUS_VERSION,
53  K_DIR_SOURCE,
54  K_DIR_OPTIONS,
55  K_CLIENT_VERSIONS,
56  K_SERVER_VERSIONS,
57  K_RECOMMENDED_CLIENT_PROTOCOLS,
58  K_RECOMMENDED_RELAY_PROTOCOLS,
59  K_REQUIRED_CLIENT_PROTOCOLS,
60  K_REQUIRED_RELAY_PROTOCOLS,
61  K_OR_ADDRESS,
62  K_ID,
63  K_P,
64  K_P6,
65  K_R,
66  K_A,
67  K_S,
68  K_V,
69  K_W,
70  K_M,
71  K_EXTRA_INFO,
72  K_EXTRA_INFO_DIGEST,
73  K_CACHES_EXTRA_INFO,
74  K_HIDDEN_SERVICE_DIR,
75  K_ALLOW_SINGLE_HOP_EXITS,
76  K_IPV6_POLICY,
77  K_ROUTER_SIG_ED25519,
78  K_IDENTITY_ED25519,
79  K_MASTER_KEY_ED25519,
80  K_ONION_KEY_CROSSCERT,
81  K_NTOR_ONION_KEY_CROSSCERT,
82 
83  K_DIRREQ_END,
84  K_DIRREQ_V2_IPS,
85  K_DIRREQ_V3_IPS,
86  K_DIRREQ_V2_REQS,
87  K_DIRREQ_V3_REQS,
88  K_DIRREQ_V2_SHARE,
89  K_DIRREQ_V3_SHARE,
90  K_DIRREQ_V2_RESP,
91  K_DIRREQ_V3_RESP,
92  K_DIRREQ_V2_DIR,
93  K_DIRREQ_V3_DIR,
94  K_DIRREQ_V2_TUN,
95  K_DIRREQ_V3_TUN,
96  K_ENTRY_END,
97  K_ENTRY_IPS,
98  K_CELL_END,
99  K_CELL_PROCESSED,
100  K_CELL_QUEUED,
101  K_CELL_TIME,
102  K_CELL_CIRCS,
103  K_EXIT_END,
104  K_EXIT_WRITTEN,
105  K_EXIT_READ,
106  K_EXIT_OPENED,
107 
108  K_DIR_KEY_CERTIFICATE_VERSION,
109  K_DIR_IDENTITY_KEY,
110  K_DIR_KEY_PUBLISHED,
111  K_DIR_KEY_EXPIRES,
112  K_DIR_KEY_CERTIFICATION,
113  K_DIR_KEY_CROSSCERT,
114  K_DIR_ADDRESS,
115  K_DIR_TUNNELLED,
116 
117  K_VOTE_STATUS,
118  K_VALID_AFTER,
119  K_FRESH_UNTIL,
120  K_VALID_UNTIL,
121  K_VOTING_DELAY,
122 
123  K_KNOWN_FLAGS,
124  K_PARAMS,
125  K_BW_WEIGHTS,
126  K_VOTE_DIGEST,
127  K_CONSENSUS_DIGEST,
128  K_ADDITIONAL_DIGEST,
129  K_ADDITIONAL_SIGNATURE,
130  K_CONSENSUS_METHODS,
131  K_CONSENSUS_METHOD,
132  K_LEGACY_DIR_KEY,
133  K_DIRECTORY_FOOTER,
134  K_SIGNING_CERT_ED,
135  K_SR_FLAG,
136  K_COMMIT,
137  K_PREVIOUS_SRV,
138  K_CURRENT_SRV,
139  K_PACKAGE,
140 
141  A_PURPOSE,
142  A_LAST_LISTED,
143  A_UNKNOWN_,
144 
145  R_RENDEZVOUS_SERVICE_DESCRIPTOR,
146  R_VERSION,
147  R_PERMANENT_KEY,
148  R_SECRET_ID_PART,
149  R_PUBLICATION_TIME,
150  R_PROTOCOL_VERSIONS,
151  R_INTRODUCTION_POINTS,
152  R_SIGNATURE,
153 
154  R_HS_DESCRIPTOR, /* From version 3, this MUST be generic to all future
155  descriptor versions thus making it R_. */
156  R3_DESC_LIFETIME,
157  R3_DESC_SIGNING_CERT,
158  R3_REVISION_COUNTER,
159  R3_SUPERENCRYPTED,
160  R3_SIGNATURE,
161  R3_CREATE2_FORMATS,
162  R3_INTRO_AUTH_REQUIRED,
163  R3_SINGLE_ONION_SERVICE,
164  R3_INTRODUCTION_POINT,
165  R3_INTRO_ONION_KEY,
166  R3_INTRO_AUTH_KEY,
167  R3_INTRO_ENC_KEY,
168  R3_INTRO_ENC_KEY_CERT,
169  R3_INTRO_LEGACY_KEY,
170  R3_INTRO_LEGACY_KEY_CERT,
171  R3_DESC_AUTH_TYPE,
172  R3_DESC_AUTH_KEY,
173  R3_DESC_AUTH_CLIENT,
174  R3_ENCRYPTED,
175 
176  R_IPO_IDENTIFIER,
177  R_IPO_IP_ADDRESS,
178  R_IPO_ONION_PORT,
179  R_IPO_ONION_KEY,
180  R_IPO_SERVICE_KEY,
181 
182  C_CLIENT_NAME,
183  C_DESCRIPTOR_COOKIE,
184  C_CLIENT_KEY,
185 
186  ERR_,
187  EOF_,
188  NIL_
190 
191 /** Structure to hold a single directory token.
192  *
193  * We parse a directory by breaking it into "tokens", each consisting
194  * of a keyword, a line full of arguments, and a binary object. The
195  * arguments and object are both optional, depending on the keyword
196  * type.
197  *
198  * This structure is only allocated in memareas; do not allocate it on
199  * the heap, or token_clear() won't work.
200  */
201 typedef struct directory_token_t {
202  directory_keyword tp; /**< Type of the token. */
203  int n_args:30; /**< Number of elements in args */
204  char **args; /**< Array of arguments from keyword line. */
205 
206  char *object_type; /**< -----BEGIN [object_type]-----*/
207  size_t object_size; /**< Bytes in object_body */
208  char *object_body; /**< Contents of object, base64-decoded. */
209 
210  struct crypto_pk_t *key; /**< For public keys only. Heap-allocated. */
211 
212  char *error; /**< For ERR_ tokens only. */
214 
215 /** We use a table of rules to decide how to parse each token type. */
216 
217 /** Rules for whether the keyword needs an object. */
218 typedef enum {
219  NO_OBJ, /**< No object, ever. */
220  NEED_OBJ, /**< Object is required. */
221  NEED_SKEY_1024,/**< Object is required, and must be a 1024 bit private key */
222  NEED_KEY_1024, /**< Object is required, and must be a 1024 bit public key */
223  NEED_KEY, /**< Object is required, and must be a public key. */
224  OBJ_OK, /**< Object is optional. */
225 } obj_syntax;
226 
227 #define AT_START 1
228 #define AT_END 2
229 
230 #define TS_ANNOTATIONS_OK 1
231 #define TS_NOCHECK 2
232 #define TS_NO_NEW_ANNOTATIONS 4
233 
234 /**
235  * @name macros for defining token rules
236  *
237  * Helper macros to define token tables. 's' is a string, 't' is a
238  * directory_keyword, 'a' is a trio of argument multiplicities, and 'o' is an
239  * object syntax.
240  */
241 /**@{*/
242 
243 /** Appears to indicate the end of a table. */
244 #define END_OF_TABLE { NULL, NIL_, 0,0,0, NO_OBJ, 0, INT_MAX, 0, 0 }
245 /** An item with no restrictions: used for obsolete document types */
246 #define T(s,t,a,o) { s, t, a, o, 0, INT_MAX, 0, 0 }
247 /** An item with no restrictions on multiplicity or location. */
248 #define T0N(s,t,a,o) { s, t, a, o, 0, INT_MAX, 0, 0 }
249 /** An item that must appear exactly once */
250 #define T1(s,t,a,o) { s, t, a, o, 1, 1, 0, 0 }
251 /** An item that must appear exactly once, at the start of the document */
252 #define T1_START(s,t,a,o) { s, t, a, o, 1, 1, AT_START, 0 }
253 /** An item that must appear exactly once, at the end of the document */
254 #define T1_END(s,t,a,o) { s, t, a, o, 1, 1, AT_END, 0 }
255 /** An item that must appear one or more times */
256 #define T1N(s,t,a,o) { s, t, a, o, 1, INT_MAX, 0, 0 }
257 /** An item that must appear no more than once */
258 #define T01(s,t,a,o) { s, t, a, o, 0, 1, 0, 0 }
259 /** An annotation that must appear no more than once */
260 #define A01(s,t,a,o) { s, t, a, o, 0, 1, 0, 1 }
261 
262 /** Argument multiplicity: any number of arguments. */
263 #define ARGS 0,INT_MAX,0
264 /** Argument multiplicity: no arguments. */
265 #define NO_ARGS 0,0,0
266 /** Argument multiplicity: concatenate all arguments. */
267 #define CONCAT_ARGS 1,1,1
268 /** Argument multiplicity: at least <b>n</b> arguments. */
269 #define GE(n) n,INT_MAX,0
270 /** Argument multiplicity: exactly <b>n</b> arguments. */
271 #define EQ(n) n,n,0
272 /**@}*/
273 
274 /** Determines the parsing rules for a single token type. */
275 typedef struct token_rule_t {
276  /** The string value of the keyword identifying the type of item. */
277  const char *t;
278  /** The corresponding directory_keyword enum. */
280  /** Minimum number of arguments for this item */
281  int min_args;
282  /** Maximum number of arguments for this item */
283  int max_args;
284  /** If true, we concatenate all arguments for this item into a single
285  * string. */
287  /** Requirements on object syntax for this item. */
289  /** Lowest number of times this item may appear in a document. */
290  int min_cnt;
291  /** Highest number of times this item may appear in a document. */
292  int max_cnt;
293  /** One or more of AT_START/AT_END to limit where the item may appear in a
294  * document. */
295  int pos;
296  /** True iff this token is an annotation. */
298 } token_rule_t;
299 
300 void token_clear(directory_token_t *tok);
301 
302 int tokenize_string(struct memarea_t *area,
303  const char *start, const char *end,
304  struct smartlist_t *out,
305  const token_rule_t *table,
306  int flags);
308  const char **s,
309  const char *eos,
310  const token_rule_t *table);
311 
313  directory_keyword keyword,
314  const char *keyword_str);
315 
316 #define find_by_keyword(s, keyword) \
317  find_by_keyword_((s), (keyword), #keyword)
318 
320  directory_keyword keyword);
321 struct smartlist_t * find_all_by_keyword(const struct smartlist_t *s,
323 
324 #endif /* !defined(TOR_PARSECOMMON_H) */
token_rule_t::min_cnt
int min_cnt
Definition: parsecommon.h:290
token_rule_t::pos
int pos
Definition: parsecommon.h:295
NEED_KEY_1024
@ NEED_KEY_1024
Definition: parsecommon.h:222
directory_token_t
Definition: parsecommon.h:201
NO_OBJ
@ NO_OBJ
Definition: parsecommon.h:219
directory_token_t::args
char ** args
Definition: parsecommon.h:204
NEED_OBJ
@ NEED_OBJ
Definition: parsecommon.h:220
token_clear
void token_clear(directory_token_t *tok)
Definition: parsecommon.c:41
token_rule_t::max_cnt
int max_cnt
Definition: parsecommon.h:292
find_all_by_keyword
smartlist_t * find_all_by_keyword(const smartlist_t *s, directory_keyword k)
Definition: parsecommon.c:468
directory_token_t::n_args
int n_args
Definition: parsecommon.h:203
NEED_SKEY_1024
@ NEED_SKEY_1024
Definition: parsecommon.h:221
get_next_token
directory_token_t * get_next_token(struct memarea_t *area, const char **s, const char *eos, const token_rule_t *table)
Definition: parsecommon.c:269
token_rule_t::is_annotation
int is_annotation
Definition: parsecommon.h:297
memarea_t
Definition: memarea.c:119
directory_token_t::object_body
char * object_body
Definition: parsecommon.h:208
find_by_keyword_
directory_token_t * find_by_keyword_(struct smartlist_t *s, directory_keyword keyword, const char *keyword_str)
Definition: parsecommon.c:441
token_rule_t::v
directory_keyword v
Definition: parsecommon.h:279
OBJ_OK
@ OBJ_OK
Definition: parsecommon.h:224
token_rule_t::os
obj_syntax os
Definition: parsecommon.h:288
directory_token_t::error
char * error
Definition: parsecommon.h:212
directory_token_t::object_size
size_t object_size
Definition: parsecommon.h:207
token_rule_t::concat_args
int concat_args
Definition: parsecommon.h:286
crypto_pk_t
Definition: crypto_rsa_nss.c:36
directory_token_t::tp
directory_keyword tp
Definition: parsecommon.h:202
directory_keyword
directory_keyword
Definition: parsecommon.h:23
NEED_KEY
@ NEED_KEY
Definition: parsecommon.h:223
obj_syntax
obj_syntax
Definition: parsecommon.h:218
find_opt_by_keyword
directory_token_t * find_opt_by_keyword(const smartlist_t *s, directory_keyword keyword)
Definition: parsecommon.c:457
token_rule_t::t
const char * t
Definition: parsecommon.h:277
tokenize_string
int tokenize_string(struct memarea_t *area, const char *start, const char *end, struct smartlist_t *out, const token_rule_t *table, int flags)
Definition: parsecommon.c:53
token_rule_t
Definition: parsecommon.h:275
token_rule_t::min_args
int min_args
Definition: parsecommon.h:281
token_rule_t::max_args
int max_args
Definition: parsecommon.h:283
smartlist_t
Definition: smartlist_core.h:26
directory_token_t::key
struct crypto_pk_t * key
Definition: parsecommon.h:210
directory_token_t::object_type
char * object_type
Definition: parsecommon.h:206