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