Tor  0.4.7.0-alpha-dev
parsecommon.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 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_KEY_1024, /**< Object is required, and must be a 1024 bit public key */
222  NEED_KEY, /**< Object is required, and must be a public key. */
223  OBJ_OK, /**< Object is optional. */
224 } obj_syntax;
225 
226 #define AT_START 1
227 #define AT_END 2
228 
229 #define TS_ANNOTATIONS_OK 1
230 #define TS_NOCHECK 2
231 #define TS_NO_NEW_ANNOTATIONS 4
232 
233 /**
234  * @name macros for defining token rules
235  *
236  * Helper macros to define token tables. 's' is a string, 't' is a
237  * directory_keyword, 'a' is a trio of argument multiplicities, and 'o' is an
238  * object syntax.
239  */
240 /**@{*/
241 
242 /** Appears to indicate the end of a table. */
243 #define END_OF_TABLE { NULL, NIL_, 0,0,0, NO_OBJ, 0, INT_MAX, 0, 0 }
244 /** An item with no restrictions: used for obsolete document types */
245 #define T(s,t,a,o) { s, t, a, o, 0, INT_MAX, 0, 0 }
246 /** An item with no restrictions on multiplicity or location. */
247 #define T0N(s,t,a,o) { s, t, a, o, 0, INT_MAX, 0, 0 }
248 /** An item that must appear exactly once */
249 #define T1(s,t,a,o) { s, t, a, o, 1, 1, 0, 0 }
250 /** An item that must appear exactly once, at the start of the document */
251 #define T1_START(s,t,a,o) { s, t, a, o, 1, 1, AT_START, 0 }
252 /** An item that must appear exactly once, at the end of the document */
253 #define T1_END(s,t,a,o) { s, t, a, o, 1, 1, AT_END, 0 }
254 /** An item that must appear one or more times */
255 #define T1N(s,t,a,o) { s, t, a, o, 1, INT_MAX, 0, 0 }
256 /** An item that must appear no more than once */
257 #define T01(s,t,a,o) { s, t, a, o, 0, 1, 0, 0 }
258 /** An annotation that must appear no more than once */
259 #define A01(s,t,a,o) { s, t, a, o, 0, 1, 0, 1 }
260 
261 /** Argument multiplicity: any number of arguments. */
262 #define ARGS 0,INT_MAX,0
263 /** Argument multiplicity: no arguments. */
264 #define NO_ARGS 0,0,0
265 /** Argument multiplicity: concatenate all arguments. */
266 #define CONCAT_ARGS 1,1,1
267 /** Argument multiplicity: at least <b>n</b> arguments. */
268 #define GE(n) n,INT_MAX,0
269 /** Argument multiplicity: exactly <b>n</b> arguments. */
270 #define EQ(n) n,n,0
271 /**@}*/
272 
273 /** Determines the parsing rules for a single token type. */
274 typedef struct token_rule_t {
275  /** The string value of the keyword identifying the type of item. */
276  const char *t;
277  /** The corresponding directory_keyword enum. */
279  /** Minimum number of arguments for this item */
280  int min_args;
281  /** Maximum number of arguments for this item */
282  int max_args;
283  /** If true, we concatenate all arguments for this item into a single
284  * string. */
286  /** Requirements on object syntax for this item. */
288  /** Lowest number of times this item may appear in a document. */
289  int min_cnt;
290  /** Highest number of times this item may appear in a document. */
291  int max_cnt;
292  /** One or more of AT_START/AT_END to limit where the item may appear in a
293  * document. */
294  int pos;
295  /** True iff this token is an annotation. */
297 } token_rule_t;
298 
299 void token_clear(directory_token_t *tok);
300 
301 int tokenize_string(struct memarea_t *area,
302  const char *start, const char *end,
303  struct smartlist_t *out,
304  const token_rule_t *table,
305  int flags);
307  const char **s,
308  const char *eos,
309  const token_rule_t *table);
310 
312  directory_keyword keyword,
313  const char *keyword_str);
314 
315 #define find_by_keyword(s, keyword) \
316  find_by_keyword_((s), (keyword), #keyword)
317 
319  directory_keyword keyword);
320 struct smartlist_t * find_all_by_keyword(const struct smartlist_t *s,
322 
323 #endif /* !defined(TOR_PARSECOMMON_H) */
directory_token_t * find_opt_by_keyword(const smartlist_t *s, directory_keyword keyword)
Definition: parsecommon.c:440
smartlist_t * find_all_by_keyword(const smartlist_t *s, directory_keyword k)
Definition: parsecommon.c:451
void token_clear(directory_token_t *tok)
Definition: parsecommon.c:41
directory_token_t * find_by_keyword_(struct smartlist_t *s, directory_keyword keyword, const char *keyword_str)
Definition: parsecommon.c:424
directory_token_t * get_next_token(struct memarea_t *area, const char **s, const char *eos, const token_rule_t *table)
Definition: parsecommon.c:261
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
obj_syntax
Definition: parsecommon.h:218
@ NEED_KEY
Definition: parsecommon.h:222
@ OBJ_OK
Definition: parsecommon.h:223
@ NO_OBJ
Definition: parsecommon.h:219
@ NEED_OBJ
Definition: parsecommon.h:220
@ NEED_KEY_1024
Definition: parsecommon.h:221
directory_keyword
Definition: parsecommon.h:23
directory_keyword tp
Definition: parsecommon.h:202
struct crypto_pk_t * key
Definition: parsecommon.h:210
obj_syntax os
Definition: parsecommon.h:287
directory_keyword v
Definition: parsecommon.h:278
const char * t
Definition: parsecommon.h:276