1 /* 2 * Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the Apache License 2.0 (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OSSL_JSON_ENC_H 11 # define OSSL_JSON_ENC_H 12 13 # include <openssl/bio.h> 14 15 /* 16 * JSON Encoder 17 * ============ 18 * 19 * This JSON encoder is used for qlog. It supports ordinary JSON (RFC 7159), 20 * JSON-SEQ (RFC 7464) and I-JSON (RFC 7493). It supports only basic ASCII. 21 */ 22 23 struct json_write_buf { 24 BIO *bio; 25 char *buf; 26 size_t alloc, cur; 27 }; 28 29 typedef struct ossl_json_enc_st { 30 uint32_t flags; 31 /* error: 1 if an error has occurred. */ 32 /* state: current state. */ 33 /* stack stores a bitmap. 0=object, 1=array. */ 34 /* stack cur size: stack_end_byte bytes, stack_end_bit bits. */ 35 /* stack alloc size: stack_bytes bytes. */ 36 unsigned char error, stack_end_bit, state, *stack, defer_indent; 37 unsigned char stack_small[16]; 38 struct json_write_buf wbuf; 39 size_t stack_end_byte, stack_bytes; 40 } OSSL_JSON_ENC; 41 42 /* 43 * ossl_json_init 44 * -------------- 45 * 46 * Initialises a JSON encoder. 47 * 48 * If the flag OSSL_JSON_FLAG_SEQ is passed, the output is in JSON-SEQ. The 49 * caller should use the encoder as though it is encoding members of a JSON 50 * array (but without calling ossl_json_array_begin() or ossl_json_array_end()). 51 * Each top-level JSON item (e.g. JSON object) encoded will be separated 52 * correctly as per the JSON-SEQ format. 53 * 54 * If the flag OSSL_JSON_FLAG_SEQ is not passed, the output is in JSON format. 55 * Generally the caller should encode only a single output item (e.g. a JSON 56 * object). 57 * 58 * By default, JSON output is maximally compact. If OSSL_JSON_FLAG_PRETTY is 59 * set, JSON/JSON-SEQ output is spaced for optimal human readability. 60 * 61 * If OSSL_JSON_FLAG_IJSON is set, integers outside the range `[-2**53 + 1, 62 * 2**53 - 1]` are automatically converted to decimal strings before 63 * serialization. 64 */ 65 #define OSSL_JSON_FLAG_NONE 0 66 #define OSSL_JSON_FLAG_SEQ (1U << 0) 67 #define OSSL_JSON_FLAG_PRETTY (1U << 1) 68 #define OSSL_JSON_FLAG_IJSON (1U << 2) 69 70 int ossl_json_init(OSSL_JSON_ENC *json, BIO *bio, uint32_t flags); 71 72 /* 73 * ossl_json_cleanup 74 * ----------------- 75 * 76 * Destroys a JSON encoder. 77 */ 78 void ossl_json_cleanup(OSSL_JSON_ENC *json); 79 80 /* 81 * ossl_json_reset 82 * --------------- 83 * 84 * Resets a JSON encoder, as though it has just been initialised, allowing it 85 * to be used again for new output syntactically unrelated to any previous 86 * output. This is similar to calling ossl_json_cleanup followed by 87 * ossl_json_init but may allow internal buffers to be reused. 88 * 89 * If the JSON encoder has entered an error state, this function MAY allow 90 * recovery from this error state, in which case it will return 1. If this 91 * function returns 0, the JSON encoder is unrecoverable and 92 * ossl_json_cleanup() must be called. 93 * 94 * Automatically calls ossl_json_flush(). 95 */ 96 int ossl_json_reset(OSSL_JSON_ENC *json); 97 98 /* 99 * ossl_json_flush 100 * --------------- 101 * 102 * Flushes the JSON encoder, ensuring that any residual bytes in internal 103 * buffers are written to the provided sink BIO. Flushing may also happen 104 * autonomously as buffers are filled, but the caller must use this function 105 * to guarantee all data has been flushed. 106 */ 107 int ossl_json_flush(OSSL_JSON_ENC *json); 108 109 /* 110 * ossl_json_flush_cleanup 111 * ----------------------- 112 * 113 * Tries to flush as in a call to ossl_json_flush, and then calls 114 * ossl_json_cleanup regardless of the result. The result of the flush call is 115 * returned. 116 */ 117 int ossl_json_flush_cleanup(OSSL_JSON_ENC *json); 118 119 /* 120 * ossl_json_set0_sink 121 * ------------------- 122 * 123 * Changes the sink used by the JSON encoder. 124 */ 125 int ossl_json_set0_sink(OSSL_JSON_ENC *json, BIO *bio); 126 127 /* 128 * ossl_json_in_error 129 * ------------------ 130 * 131 * To enhance the ergonomics of the JSON API, the JSON object uses an implicit 132 * error tracking model. When a JSON API call fails (for example due to caller 133 * error, such as trying to close an array which was not opened), the JSON 134 * object enters an error state and all further calls are silently ignored. 135 * 136 * The caller can detect this condition after it is finished making builder 137 * calls to the JSON object by calling this function. This function returns 1 138 * if an error occurred. At this point the caller's only recourse is to call 139 * ossl_json_reset() or ossl_json_cleanup(). 140 * 141 * Note that partial (i.e., invalid) output may still have been sent to the BIO 142 * in this case. Since the amount of output which can potentially be produced 143 * by a JSON object is unbounded, it is impractical to buffer it all before 144 * flushing. It is expected that errors will ordinarily be either caller errors 145 * (programming errors) or BIO errors. 146 */ 147 int ossl_json_in_error(OSSL_JSON_ENC *json); 148 149 /* 150 * JSON Builder Calls 151 * ================== 152 * 153 * These functions are used to build JSON output. The functions which have 154 * begin and end function pairs must be called in correctly nested sequence. 155 * When writing an object, ossl_json_key() must be called exactly once before 156 * each call to write a JSON item. 157 * 158 * The JSON library takes responsibility for enforcing correct usage patterns. 159 * If a call is made that does not correspond to the JSON syntax, the JSON 160 * object enters the error state and all subsequent calls are ignored. 161 * 162 * In JSON-SEQ mode, the caller should act as though the library implicitly 163 * places all calls between an ossl_json_array_begin() and 164 * ossl_json_array_end() pair; for example, the normal usage pattern would be 165 * to call ossl_json_object_begin() followed by ossl_json_object_end(), in 166 * repeated sequence. 167 * 168 * The library does not enforce non-generation of duplicate keys. Avoiding this 169 * is the caller's responsibility. It is also the caller's responsibility to 170 * pass valid UTF-8 strings. All other forms of invalid output will cause an 171 * error. Note that due to the immediate nature of the API, partial output may 172 * have already been generated in such a case. 173 */ 174 175 /* Begin a new JSON object. */ 176 void ossl_json_object_begin(OSSL_JSON_ENC *json); 177 178 /* End a JSON object. Must be matched with a call to ossl_json_object_begin(). */ 179 void ossl_json_object_end(OSSL_JSON_ENC *json); 180 181 /* Begin a new JSON array. */ 182 void ossl_json_array_begin(OSSL_JSON_ENC *json); 183 184 /* End a JSON array. Must be matched with a call to ossl_json_array_end(). */ 185 void ossl_json_array_end(OSSL_JSON_ENC *json); 186 187 /* 188 * Encode a JSON key within an object. Pass a zero-terminated string, which can 189 * be freed immediately following the call to this function. 190 */ 191 void ossl_json_key(OSSL_JSON_ENC *json, const char *key); 192 193 /* Encode a JSON 'null' value. */ 194 void ossl_json_null(OSSL_JSON_ENC *json); 195 196 /* Encode a JSON boolean value. */ 197 void ossl_json_bool(OSSL_JSON_ENC *json, int value); 198 199 /* Encode a JSON integer from a uint64_t. */ 200 void ossl_json_u64(OSSL_JSON_ENC *json, uint64_t value); 201 202 /* Encode a JSON integer from an int64_t. */ 203 void ossl_json_i64(OSSL_JSON_ENC *json, int64_t value); 204 205 /* Encode a JSON number from a 64-bit floating point value. */ 206 void ossl_json_f64(OSSL_JSON_ENC *json, double value); 207 208 /* 209 * Encode a JSON UTF-8 string from a zero-terminated string. The string passed 210 * can be freed immediately following the call to this function. 211 */ 212 void ossl_json_str(OSSL_JSON_ENC *json, const char *str); 213 214 /* 215 * Encode a JSON UTF-8 string from a string with the given length. The string 216 * passed can be freed immediately following the call to this function. 217 */ 218 void ossl_json_str_len(OSSL_JSON_ENC *json, const char *str, size_t str_len); 219 220 /* 221 * Encode binary data as a lowercase hex string. data_len is the data length in 222 * bytes. 223 */ 224 void ossl_json_str_hex(OSSL_JSON_ENC *json, const void *data, size_t data_len); 225 226 #endif 227
