src/include/gnunet_json_lib.h

   1 /*
   2    This file is part of GNUnet
   3    Copyright (C) 2014, 2015, 2016 GNUnet e.V.
   4
   5    GNUnet is free software: you can redistribute it and/or modify it
   6    under the terms of the GNU Affero General Public License as published
   7    by the Free Software Foundation, either version 3 of the License,
   8    or (at your option) any later version.
   9
  10    GNUnet is distributed in the hope that it will be useful, but
  11    WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Affero General Public License for more details.
  14
  15    You should have received a copy of the GNU Affero General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20 /**
  21  * @file gnunet_json_lib.h
  22  * @brief functions to parse JSON objects into GNUnet objects
  23  * @author Florian Dold
  24  * @author Benedikt Mueller
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_JSON_LIB_H
  28 #define GNUNET_JSON_LIB_H
  29
  30 #include "gnunet_util_lib.h"
  31 #include "gnunet_gnsrecord_lib.h"
  32 #include <jansson.h>
  33 #include <microhttpd.h>
  34
  35 /* ****************** Generic parser interface ******************* */
  36
  37 /**
  38  * @brief Entry in parser specification for #GNUNET_JSON_parse().
  39  */
  40 struct GNUNET_JSON_Specification;
  41
  42
  43 /**
  44  * Function called to parse JSON argument.
  45  *
  46  * @param cls closure
  47  * @param root JSON to parse
  48  * @param spec our specification entry with further details
  49  * @return #GNUNET_SYSERR on error,
  50  *         #GNUNET_OK on success
  51  */
  52 typedef int (*GNUNET_JSON_Parser) (void *cls,
  53                                    json_t *root,
  54                                    struct GNUNET_JSON_Specification *spec);
  55
  56
  57 /**
  58  * Function called to clean up data from earlier parsing.
  59  *
  60  * @param cls closure
  61  * @param spec our specification entry with data to clean.
  62  */
  63 typedef void (*GNUNET_JSON_Cleaner) (void *cls,
  64                                      struct GNUNET_JSON_Specification *spec);
  65
  66
  67 /**
  68  * @brief Entry in parser specification for #GNUNET_JSON_parse().
  69  */
  70 struct GNUNET_JSON_Specification
  71 {
  72   /**
  73    * Function for how to parse this type of entry.
  74    */
  75   GNUNET_JSON_Parser parser;
  76
  77   /**
  78    * Function for how to clean up this type of entry.
  79    */
  80   GNUNET_JSON_Cleaner cleaner;
  81
  82   /**
  83    * Closure for @e parser and @e cleaner.
  84    */
  85   void *cls;
  86
  87   /**
  88    * Name of the field to parse, use NULL to get the JSON
  89    * of the main object instead of the JSON of an individual field.
  90    */
  91   const char *field;
  92
  93   /**
  94    * Pointer, details specific to the @e parser.
  95    */
  96   void *ptr;
  97
  98   /**
  99    * Number of bytes available in @e ptr.
 100    */
 101   size_t ptr_size;
 102
 103   /**
 104    * Where should we store the final size of @e ptr.
 105    */
 106   size_t *size_ptr;
 107
 108   /**
 109    * Set to #GNUNET_YES if this component is optional.
 110    */
 111   int is_optional;
 112 };
 113
 114
 115 /**
 116  * Navigate and parse data in a JSON tree.  Tries to parse the @a root
 117  * to find all of the values given in the @a spec.  If one of the
 118  * entries in @a spec cannot be found or parsed, the name of the JSON
 119  * field is returned in @a error_json_name, and the offset of the
 120  * entry in @a spec is returned in @a error_line.
 121  *
 122  * @param root the JSON node to start the navigation at.
 123  * @param spec parse specification array
 124  * @param[out] error_json_name which JSON field was problematic
 125  * @param[out] which index into @a spec did we encounter an error
 126  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 127  */
 128 int
 129 GNUNET_JSON_parse (const json_t *root,
 130                    struct GNUNET_JSON_Specification *spec,
 131                    const char **error_json_name,
 132                    unsigned int *error_line);
 133
 134
 135 /**
 136  * Frees all elements allocated during a #GNUNET_JSON_parse()
 137  * operation.
 138  *
 139  * @param spec specification of the parse operation
 140  */
 141 void
 142 GNUNET_JSON_parse_free (struct GNUNET_JSON_Specification *spec);
 143
 144
 145 /* ****************** Canonical parser specifications ******************* */
 146
 147
 148 /**
 149  * End of a parser specification.
 150  */
 151 struct GNUNET_JSON_Specification
 152 GNUNET_JSON_spec_end (void);
 153
 154
 155 /**
 156  * Set the "optional" flag for a parser specification entry.
 157  *
 158  * @param spec specification to modify
 159  * @return spec copy of @a spec with optional bit set
 160  */
 161 struct GNUNET_JSON_Specification
 162 GNUNET_JSON_spec_mark_optional (struct GNUNET_JSON_Specification spec);
 163
 164
 165 /**
 166  * Variable size object (in network byte order, encoded using Crockford
 167  * Base32hex encoding).
 168  *
 169  * @param name name of the JSON field
 170  * @param[out] obj pointer where to write the data, must have @a size bytes
 171  * @param size number of bytes expected in @a obj
 172  */
 173 struct GNUNET_JSON_Specification
 174 GNUNET_JSON_spec_fixed (const char *name, void *obj, size_t size);
 175
 176
 177 /**
 178  * Fixed size object (in network byte order, encoded using Crockford
 179  * Base32hex encoding).
 180  *
 181  * @param name name of the JSON field
 182  * @param obj pointer where to write the data (type of `*obj` will determine size)
 183  */
 184 #define GNUNET_JSON_spec_fixed_auto(name, obj) \
 185   GNUNET_JSON_spec_fixed (name, obj, sizeof(*obj))
 186
 187
 188 /**
 189  * Variable size object (in network byte order, encoded using
 190  * Crockford Base32hex encoding).
 191  *
 192  * @param name name of the JSON field
 193  * @param[out] obj pointer where to write the data, will be allocated
 194  * @param[out] size where to store the number of bytes allocated for @a obj
 195  */
 196 struct GNUNET_JSON_Specification
 197 GNUNET_JSON_spec_varsize (const char *name, void **obj, size_t *size);
 198
 199
 200 /**
 201  * The expected field stores a string.
 202  *
 203  * @param name name of the JSON field
 204  * @param strptr where to store a pointer to the field
 205  */
 206 struct GNUNET_JSON_Specification
 207 GNUNET_JSON_spec_string (const char *name, const char **strptr);
 208
 209 /**
 210  * JSON object.
 211  *
 212  * @param name name of the JSON field
 213  * @param[out] jsonp where to store the JSON found under @a name
 214  */
 215 struct GNUNET_JSON_Specification
 216 GNUNET_JSON_spec_json (const char *name, json_t **jsonp);
 217
 218
 219 /**
 220  * 8-bit integer.
 221  *
 222  * @param name name of the JSON field
 223  * @param[out] u8 where to store the integer found under @a name
 224  */
 225 struct GNUNET_JSON_Specification
 226 GNUNET_JSON_spec_uint8 (const char *name, uint8_t *u8);
 227
 228
 229 /**
 230  * 16-bit integer.
 231  *
 232  * @param name name of the JSON field
 233  * @param[out] u16 where to store the integer found under @a name
 234  */
 235 struct GNUNET_JSON_Specification
 236 GNUNET_JSON_spec_uint16 (const char *name, uint16_t *u16);
 237
 238
 239 /**
 240  * 32-bit integer.
 241  *
 242  * @param name name of the JSON field
 243  * @param[out] u32 where to store the integer found under @a name
 244  */
 245 struct GNUNET_JSON_Specification
 246 GNUNET_JSON_spec_uint32 (const char *name, uint32_t *u32);
 247
 248
 249 /**
 250  * 64-bit integer.
 251  *
 252  * @param name name of the JSON field
 253  * @param[out] u64 where to store the integer found under @a name
 254  */
 255 struct GNUNET_JSON_Specification
 256 GNUNET_JSON_spec_uint64 (const char *name, uint64_t *u64);
 257
 258
 259 /**
 260  * Boolean (true mapped to #GNUNET_YES, false mapped to #GNUNET_NO).
 261  *
 262  * @param name name of the JSON field
 263  * @param[out] boolean where to store the boolean found under @a name
 264  */
 265 struct GNUNET_JSON_Specification
 266 GNUNET_JSON_spec_boolean (const char *name, int *boolean);
 267
 268
 269 /* ************ GNUnet-specific parser specifications ******************* */
 270
 271 /**
 272  * Absolute time.
 273  *
 274  * @param name name of the JSON field
 275  * @param[out] at where to store the absolute time found under @a name
 276  */
 277 struct GNUNET_JSON_Specification
 278 GNUNET_JSON_spec_absolute_time (const char *name,
 279                                 struct GNUNET_TIME_Absolute *at);
 280
 281
 282 /**
 283  * Absolute time in network byte order.
 284  *
 285  * @param name name of the JSON field
 286  * @param[out] at where to store the absolute time found under @a name
 287  */
 288 struct GNUNET_JSON_Specification
 289 GNUNET_JSON_spec_absolute_time_nbo (const char *name,
 290                                     struct GNUNET_TIME_AbsoluteNBO *at);
 291
 292
 293 /**
 294  * Relative time.
 295  *
 296  * @param name name of the JSON field
 297  * @param[out] rt where to store the relative time found under @a name
 298  */
 299 struct GNUNET_JSON_Specification
 300 GNUNET_JSON_spec_relative_time (const char *name,
 301                                 struct GNUNET_TIME_Relative *rt);
 302
 303
 304 /**
 305  * Specification for parsing an RSA public key.
 306  *
 307  * @param name name of the JSON field
 308  * @param pk where to store the RSA key found under @a name
 309  */
 310 struct GNUNET_JSON_Specification
 311 GNUNET_JSON_spec_rsa_public_key (const char *name,
 312                                  struct GNUNET_CRYPTO_RsaPublicKey **pk);
 313
 314
 315 /**
 316  * Specification for parsing an RSA signature.
 317  *
 318  * @param name name of the JSON field
 319  * @param sig where to store the RSA signature found under @a name
 320  */
 321 struct GNUNET_JSON_Specification
 322 GNUNET_JSON_spec_rsa_signature (const char *name,
 323                                 struct GNUNET_CRYPTO_RsaSignature **sig);
 324
 325
 326 /**
 327  * JSON Specification for GNS Records.
 328  *
 329  * @param gnsrecord_object struct of GNUNET_GNSRECORD_Data to fill
 330  * @return JSON Specification
 331  */
 332 struct GNUNET_JSON_Specification
 333 GNUNET_JSON_spec_gnsrecord (struct GNUNET_GNSRECORD_Data **rd,
 334                             unsigned int *rd_count,
 335                             char **name);
 336
 337
 338 /* ****************** Generic generator interface ******************* */
 339
 340
 341 /**
 342  * Convert binary data to a JSON string with the base32crockford
 343  * encoding.
 344  *
 345  * @param data binary data
 346  * @param size size of @a data in bytes
 347  * @return json string that encodes @a data
 348  */
 349 json_t *
 350 GNUNET_JSON_from_data (const void *data, size_t size);
 351
 352
 353 /**
 354  * Convert binary data to a JSON string with the base32crockford
 355  * encoding.
 356  *
 357  * @param ptr binary data, sizeof (*ptr) must yield correct size
 358  * @return json string that encodes @a data
 359  */
 360 #define GNUNET_JSON_from_data_auto(ptr) \
 361   GNUNET_JSON_from_data (ptr, sizeof(*ptr))
 362
 363
 364 /**
 365  * Convert absolute timestamp to a json string.
 366  *
 367  * @param stamp the time stamp
 368  * @return a json string with the timestamp in @a stamp
 369  */
 370 json_t *
 371 GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
 372
 373
 374 /**
 375  * Convert absolute timestamp to a json string.
 376  *
 377  * @param stamp the time stamp
 378  * @return a json string with the timestamp in @a stamp
 379  */
 380 json_t *
 381 GNUNET_JSON_from_time_abs_nbo (struct GNUNET_TIME_AbsoluteNBO stamp);
 382
 383
 384 /**
 385  * Convert relative timestamp to a json string.
 386  *
 387  * @param stamp the time stamp
 388  * @return a json string with the timestamp in @a stamp
 389  */
 390 json_t *
 391 GNUNET_JSON_from_time_rel (struct GNUNET_TIME_Relative stamp);
 392
 393
 394 /**
 395  * Convert RSA public key to JSON.
 396  *
 397  * @param pk public key to convert
 398  * @return corresponding JSON encoding
 399  */
 400 json_t *
 401 GNUNET_JSON_from_rsa_public_key (const struct GNUNET_CRYPTO_RsaPublicKey *pk);
 402
 403
 404 /**
 405  * Convert RSA signature to JSON.
 406  *
 407  * @param sig signature to convert
 408  * @return corresponding JSON encoding
 409  */
 410 json_t *
 411 GNUNET_JSON_from_rsa_signature (const struct GNUNET_CRYPTO_RsaSignature *sig);
 412
 413 /**
 414  * Convert Gns record to JSON.
 415  *
 416  * @param rname name of record
 417  * @param rd record data
 418  * @return corresponding JSON encoding
 419  */
 420 json_t *
 421 GNUNET_JSON_from_gnsrecord (const char *rname,
 422                             const struct GNUNET_GNSRECORD_Data *rd,
 423                             unsigned int rd_count);
 424
 425 /* ******************* Helpers for MHD upload handling ******************* */
 426
 427 /**
 428  * Return codes from #GNUNET_JSON_post_parser().
 429  */
 430 enum GNUNET_JSON_PostResult
 431 {
 432   /**
 433    * Parsing successful, JSON result is in `*json`.
 434    */
 435   GNUNET_JSON_PR_SUCCESS,
 436
 437   /**
 438    * Parsing continues, call again soon!
 439    */
 440   GNUNET_JSON_PR_CONTINUE,
 441
 442   /**
 443    * Sorry, memory allocation (malloc()) failed.
 444    */
 445   GNUNET_JSON_PR_OUT_OF_MEMORY,
 446
 447   /**
 448    * Request size exceeded `buffer_max` argument.
 449    */
 450   GNUNET_JSON_PR_REQUEST_TOO_LARGE,
 451
 452   /**
 453    * JSON parsing failed. This was not a JSON upload.
 454    */
 455   GNUNET_JSON_PR_JSON_INVALID
 456 };
 457
 458
 459 /**
 460  * Process a POST request containing a JSON object.  This function
 461  * realizes an MHD POST processor that will (incrementally) process
 462  * JSON data uploaded to the HTTP server.  It will store the required
 463  * state in the @a con_cls, which must be cleaned up using
 464  * #GNUNET_JSON_post_parser_callback().
 465  *
 466  * @param buffer_max maximum allowed size for the buffer
 467  * @param connection MHD connection handle (for meta data about the upload)
 468  * @param con_cls the closure (will point to a `struct Buffer *`)
 469  * @param upload_data the POST data
 470  * @param upload_data_size number of bytes in @a upload_data
 471  * @param json the JSON object for a completed request
 472  * @return result code indicating the status of the operation
 473  */
 474 enum GNUNET_JSON_PostResult
 475 GNUNET_JSON_post_parser (size_t buffer_max,
 476                          struct MHD_Connection *connection,
 477                          void **con_cls,
 478                          const char *upload_data,
 479                          size_t *upload_data_size,
 480                          json_t **json);
 481
 482
 483 /**
 484  * Function called whenever we are done with a request
 485  * to clean up our state.
 486  *
 487  * @param con_cls value as it was left by
 488  *        #GNUNET_JSON_post_parser(), to be cleaned up
 489  */
 490 void
 491 GNUNET_JSON_post_parser_cleanup (void *con_cls);
 492
 493
 494 /* ****************** GETOPT JSON helper ******************* */
 495
 496
 497 /**
 498  * Allow user to specify a JSON input value.
 499  *
 500  * @param shortName short name of the option
 501  * @param name long name of the option
 502  * @param argumentHelp help text for the option argument
 503  * @param description long help text for the option
 504  * @param[out] val set to the JSON specified at the command line
 505  */
 506 struct GNUNET_GETOPT_CommandLineOption
 507 GNUNET_JSON_getopt (char shortName,
 508                     const char *name,
 509                     const char *argumentHelp,
 510                     const char *description,
 511                     json_t **json);
 512
 513 #endif
 514
 515 /* end of gnunet_json_lib.h */