]>
git.ipfire.org Git - thirdparty/openssl.git/blob - include/internal/json_enc.h
5767b3e575c9ae5b600ccc9ae749253ee2531ce6
2 * Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
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
10 #ifndef OSSL_JSON_ENC_H
11 # define OSSL_JSON_ENC_H
13 # include <openssl/bio.h>
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.
23 struct json_write_buf
{
29 typedef struct ossl_json_enc_st
{
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
;
46 * Initialises a JSON encoder.
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.
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
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.
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
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)
70 int ossl_json_init(OSSL_JSON_ENC
*json
, BIO
*bio
, uint32_t flags
);
76 * Destroys a JSON encoder.
78 void ossl_json_cleanup(OSSL_JSON_ENC
*json
);
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.
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.
94 * Automatically calls ossl_json_flush().
96 int ossl_json_reset(OSSL_JSON_ENC
*json
);
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.
107 int ossl_json_flush(OSSL_JSON_ENC
*json
);
110 * ossl_json_flush_cleanup
111 * -----------------------
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
117 int ossl_json_flush_cleanup(OSSL_JSON_ENC
*json
);
120 * ossl_json_set0_sink
121 * -------------------
123 * Changes the sink used by the JSON encoder.
125 int ossl_json_set0_sink(OSSL_JSON_ENC
*json
, BIO
*bio
);
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.
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().
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.
147 int ossl_json_in_error(OSSL_JSON_ENC
*json
);
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.
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.
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
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.
175 /* Begin a new JSON object. */
176 void ossl_json_object_begin(OSSL_JSON_ENC
*json
);
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
);
181 /* Begin a new JSON array. */
182 void ossl_json_array_begin(OSSL_JSON_ENC
*json
);
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
);
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.
191 void ossl_json_key(OSSL_JSON_ENC
*json
, const char *key
);
193 /* Encode a JSON 'null' value. */
194 void ossl_json_null(OSSL_JSON_ENC
*json
);
196 /* Encode a JSON boolean value. */
197 void ossl_json_bool(OSSL_JSON_ENC
*json
, int value
);
199 /* Encode a JSON integer from a uint64_t. */
200 void ossl_json_u64(OSSL_JSON_ENC
*json
, uint64_t value
);
202 /* Encode a JSON integer from an int64_t. */
203 void ossl_json_i64(OSSL_JSON_ENC
*json
, int64_t value
);
205 /* Encode a JSON number from a 64-bit floating point value. */
206 void ossl_json_f64(OSSL_JSON_ENC
*json
, double value
);
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.
212 void ossl_json_str(OSSL_JSON_ENC
*json
, const char *str
);
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.
218 void ossl_json_str_len(OSSL_JSON_ENC
*json
, const char *str
, size_t str_len
);
221 * Encode binary data as a lowercase hex string. data_len is the data length in
224 void ossl_json_str_hex(OSSL_JSON_ENC
*json
, const void *data
, size_t data_len
);