lsquic_parse.h revision f07b3eae 
1/* Copyright (c) 2017 - 2021 LiteSpeed Technologies Inc.  See LICENSE. */
2#ifndef LSQUIC_PARSE_H
3#define LSQUIC_PARSE_H 1
4
5#include <stdint.h>
6
7#include "lsquic_packet_common.h"
8#include "lsquic_packet_gquic.h"
9#include "lsquic_shared_support.h"
10
11struct lsquic_conn;
12struct lsquic_packet_in;
13struct lsquic_packet_out;
14struct packin_parse_state;
15struct stream_frame;
16struct lsquic_cid;
17enum packet_out_flags;
18enum lsquic_version;
19enum stream_dir;
20
21
22struct ack_info
23{
24    enum packnum_space pns;
25    enum {
26        AI_ECN        = 1 << 0, /* ecn_counts[1,2,3] contain ECN counts */
27        AI_TRUNCATED  = 1 << 1, /* There were more ranges to parse, but we
28                                 * ran out of elements in `ranges'.
29                                 */
30    }               flags;
31    unsigned    n_ranges;       /* This is at least 1 */
32                                /* Largest acked is ack_info.ranges[0].high */
33    lsquic_time_t   lack_delta;
34    uint64_t        ecn_counts[4];
35    struct lsquic_packno_range ranges[256];
36};
37
38#define largest_acked(acki) (+(acki)->ranges[0].high)
39
40#define smallest_acked(acki) (+(acki)->ranges[(acki)->n_ranges - 1].low)
41
42/* Chrome may send an empty ACK frame when it closes a connection.
43 * We do not know why it occurs -- perhaps a bug in Chrome.
44 */
45/* This macro cannot be used in IETF QUIC as zero is a valid packet number.
46 * Hopefully the Chrome bug will have been fixed by then.
47 */
48#define empty_ack_frame(acki) (largest_acked(acki) == 0)
49
50/* gaf_: generate ACK frame */
51struct lsquic_packno_range;
52typedef const struct lsquic_packno_range *
53    (*gaf_rechist_first_f)          (void *rechist);
54typedef const struct lsquic_packno_range *
55    (*gaf_rechist_next_f)           (void *rechist);
56typedef lsquic_time_t
57    (*gaf_rechist_largest_recv_f)   (void *rechist);
58
59/* gsf_: generate stream frame */
60typedef size_t (*gsf_read_f) (void *stream, void *buf, size_t len, int *fin);
61
62/* This structure contains functions that parse and generate packets and
63 * frames in version-specific manner.  To begin with, there is difference
64 * between GQUIC's little-endian (Q038 and lower) and big-endian formats
65 * (Q039 and higher).  Q046 and higher uses different format for packet headers.
66 */
67struct parse_funcs
68{
69    /* Return buf length */
70    int
71    (*pf_gen_reg_pkt_header) (const struct lsquic_conn *,
72                const struct lsquic_packet_out *, unsigned char *, size_t,
73                /* In Q050 and IETF QUIC, these are set: */
74                unsigned *packno_off, unsigned *packno_len);
75    void
76    (*pf_parse_packet_in_finish) (struct lsquic_packet_in *packet_in,
77                                                struct packin_parse_state *);
78    enum quic_frame_type
79    (*pf_parse_frame_type) (const unsigned char *, size_t);
80    /* Return used buffer length or a negative value if there was not enough
81     * room to write the stream frame.  In the latter case, the negative of
82     * the negative return value is the number of bytes required.  The
83     * exception is -1, which is a generic error code, as we always need
84     * more than 1 byte to write a STREAM frame.
85     */
86    /* pf_gen_stream_frame and pf_gen_crypto_frame must be adjacent so that
87     * they can be cast to an array.
88     */
89    int
90    (*pf_gen_stream_frame) (unsigned char *buf, size_t bufsz,
91                            lsquic_stream_id_t stream_id, uint64_t offset,
92                            int fin, size_t size, gsf_read_f, void *stream);
93    /* The two "UNUSED" parameters are here so that it matches
94     * pf_gen_stream_frame.
95     */
96    int
97    (*pf_gen_crypto_frame) (unsigned char *buf, size_t bufsz,
98                            lsquic_stream_id_t UNUSED_1, uint64_t offset,
99                            int UNUSED_2, size_t size, gsf_read_f, void *stream);
100    /* pf_parse_stream_frame and pf_parse_crypto_frame must be adjacent so that
101     * they can be cast to an array.
102     */
103    int
104    (*pf_parse_stream_frame) (const unsigned char *buf, size_t rem_packet_sz,
105                                                    struct stream_frame *);
106    int
107    (*pf_parse_crypto_frame) (const unsigned char *buf, size_t rem_packet_sz,
108                                                    struct stream_frame *);
109    /* Return true if STREAM frame extends to the end of the packet and thus
110     * does not contain a Length field (no update).
111     */
112    int
113    (*pf_dec_stream_frame_size) (unsigned char *buf, size_t new_size);
114    int
115    (*pf_parse_ack_frame) (const unsigned char *buf, size_t buf_len,
116                                    struct ack_info *ack_info, uint8_t exp);
117    int
118    (*pf_gen_ack_frame) (unsigned char *outbuf, size_t outbuf_sz,
119                gaf_rechist_first_f, gaf_rechist_next_f,
120                gaf_rechist_largest_recv_f, void *rechist, lsquic_time_t now,
121                int *has_missing, lsquic_packno_t *largest_received,
122                const uint64_t *ecn_counts);
123    int
124    (*pf_gen_stop_waiting_frame) (unsigned char *buf, size_t buf_len,
125                    lsquic_packno_t cur_packno, enum packno_bits,
126                    lsquic_packno_t least_unacked_packno);
127    int
128    (*pf_parse_stop_waiting_frame) (const unsigned char *buf, size_t buf_len,
129                     lsquic_packno_t cur_packno, enum packno_bits,
130                     lsquic_packno_t *least_unacked);
131    int
132    (*pf_skip_stop_waiting_frame) (size_t buf_len, enum packno_bits);
133    int
134    (*pf_gen_window_update_frame) (unsigned char *buf, int buf_len,
135                                lsquic_stream_id_t stream_id, uint64_t offset);
136    int
137    (*pf_parse_window_update_frame) (const unsigned char *buf, size_t buf_len,
138                              lsquic_stream_id_t *stream_id, uint64_t *offset);
139    /* The third argument for pf_gen_blocked_frame() and pf_parse_blocked_frame()
140     * is Stream ID for GQUIC and offset for IETF QUIC.  Since both of these are
141     * uint64_t, we'll use the same function pointer.  Just have to be a little
142     * careful here.
143     */
144    int
145    (*pf_gen_blocked_frame) (unsigned char *buf, size_t buf_len,
146                                                lsquic_stream_id_t stream_id);
147    int
148    (*pf_parse_blocked_frame) (const unsigned char *buf, size_t buf_len,
149        /* TODO: rename third argument when dropping GQUIC */
150                                                lsquic_stream_id_t *stream_id);
151    unsigned
152    (*pf_blocked_frame_size) (uint64_t);
153    unsigned
154    (*pf_rst_frame_size) (lsquic_stream_id_t stream_id, uint64_t final_size,
155                                                        uint64_t error_code);
156    int
157    (*pf_gen_rst_frame) (unsigned char *buf, size_t buf_len,
158        lsquic_stream_id_t stream_id, uint64_t offset, uint64_t error_code);
159    int
160    (*pf_parse_rst_frame) (const unsigned char *buf, size_t buf_len,
161        lsquic_stream_id_t *stream_id, uint64_t *offset, uint64_t *error_code);
162    int
163    (*pf_parse_stop_sending_frame) (const unsigned char *buf, size_t buf_len,
164        lsquic_stream_id_t *stream_id, uint64_t *error_code);
165    unsigned
166    (*pf_stop_sending_frame_size) (lsquic_stream_id_t, uint64_t);
167    int
168    (*pf_gen_stop_sending_frame) (unsigned char *buf, size_t buf_len,
169                                    lsquic_stream_id_t, uint64_t error_code);
170    size_t
171    (*pf_connect_close_frame_size) (int app_error, unsigned error_code,
172                                unsigned frame_type, size_t reason_len);
173    int
174    (*pf_gen_connect_close_frame) (unsigned char *buf, size_t buf_len,
175        int app_error, unsigned error_code, const char *reason, int reason_len);
176    int
177    (*pf_parse_connect_close_frame) (const unsigned char *buf, size_t buf_len,
178                int *app_error, uint64_t *error_code, uint16_t *reason_length,
179                uint8_t *reason_offset);
180    int
181    (*pf_gen_goaway_frame) (unsigned char *buf, size_t buf_len,
182                uint32_t error_code, lsquic_stream_id_t last_good_stream_id,
183                const char *reason, size_t reason_len);
184    int
185    (*pf_parse_goaway_frame) (const unsigned char *buf, size_t buf_len,
186                uint32_t *error_code, lsquic_stream_id_t *last_good_stream_id,
187                uint16_t *reason_length, const char **reason);
188    int
189    (*pf_gen_ping_frame) (unsigned char *buf, int buf_len);
190    int
191    (*pf_parse_path_chal_frame) (const unsigned char *buf, size_t,
192                                                            uint64_t *chal);
193    int
194    (*pf_parse_path_resp_frame) (const unsigned char *buf, size_t,
195                                                            uint64_t *resp);
196    /* These float reading and writing functions assume `mem' has at least
197     * 2 bytes.
198     */
199    void
200    (*pf_write_float_time16) (lsquic_time_t time_us, void *mem);
201    uint64_t
202    (*pf_read_float_time16) (const void *mem);
203    ssize_t
204    (*pf_generate_simple_prst) (const lsquic_cid_t *cid,
205                                                    unsigned char *, size_t);
206    size_t
207    (*pf_calc_stream_frame_header_sz) (lsquic_stream_id_t stream_id,
208                                            uint64_t offset, unsigned data_sz);
209    size_t
210    (*pf_calc_crypto_frame_header_sz) (uint64_t offset, unsigned data_sz);
211    void
212    (*pf_turn_on_fin) (unsigned char *);
213
214    size_t
215    (*pf_packout_size) (const struct lsquic_conn *,
216                                            const struct lsquic_packet_out *);
217
218    /* This returns the high estimate of the header size.  Note that it
219     * cannot account for the size of the token in the IETF QUIC Initial
220     * packets as it does not know it.
221     */
222    size_t
223    (*pf_packout_max_header_size) (const struct lsquic_conn *,
224                    enum packet_out_flags, size_t dcid_len, enum header_type);
225
226    enum packno_bits
227    (*pf_calc_packno_bits) (lsquic_packno_t packno,
228                        lsquic_packno_t least_unacked, uint64_t n_in_flight);
229    unsigned
230    (*pf_packno_bits2len) (enum packno_bits);
231
232    int
233    (*pf_parse_max_data) (const unsigned char *, size_t, uint64_t *);
234    int
235    (*pf_gen_max_data_frame) (unsigned char *, size_t, uint64_t);
236    unsigned
237    (*pf_max_data_frame_size) (uint64_t);
238    /*
239     * Returns number of bytes parsed on success or negative value on error:
240     *  -1  Out of input buffer
241     *  -2  Invalid CID length value
242     */
243    int
244    (*pf_parse_new_conn_id) (const unsigned char *, size_t, uint64_t *,
245                        uint64_t *, lsquic_cid_t *, const unsigned char **);
246    unsigned
247    (*pf_stream_blocked_frame_size) (lsquic_stream_id_t, uint64_t);
248    int
249    (*pf_gen_stream_blocked_frame) (unsigned char *buf, size_t,
250                                                lsquic_stream_id_t, uint64_t);
251    int
252    (*pf_parse_stream_blocked_frame) (const unsigned char *buf, size_t,
253                                            lsquic_stream_id_t *, uint64_t *);
254    unsigned
255    (*pf_max_stream_data_frame_size) (lsquic_stream_id_t, uint64_t);
256    int
257    (*pf_gen_max_stream_data_frame) (unsigned char *buf, size_t,
258                                                lsquic_stream_id_t, uint64_t);
259    int
260    (*pf_parse_max_stream_data_frame) (const unsigned char *buf, size_t,
261                                            lsquic_stream_id_t *, uint64_t *);
262    int
263    (*pf_parse_new_token_frame) (const unsigned char *buf, size_t,
264                            const unsigned char **token, size_t *token_size);
265    size_t
266    (*pf_new_connection_id_frame_size) (unsigned seqno, unsigned cid_len);
267    int
268    (*pf_gen_new_connection_id_frame) (unsigned char *buf, size_t,
269                unsigned seqno, const struct lsquic_cid *,
270                const unsigned char *token, size_t);
271    size_t
272    (*pf_retire_cid_frame_size) (uint64_t);
273    int
274    (*pf_gen_retire_cid_frame) (unsigned char *buf, size_t, uint64_t);
275    int
276    (*pf_parse_retire_cid_frame) (const unsigned char *buf, size_t, uint64_t *);
277    size_t
278    (*pf_new_token_frame_size) (size_t);
279    int
280    (*pf_gen_new_token_frame) (unsigned char *buf, size_t,
281                                        const unsigned char *token, size_t);
282    int
283    (*pf_gen_streams_blocked_frame) (unsigned char *buf, size_t buf_len,
284                                        enum stream_dir, uint64_t);
285    int
286    (*pf_parse_streams_blocked_frame) (const unsigned char *buf, size_t buf_len,
287                                        enum stream_dir *, uint64_t *);
288    unsigned
289    (*pf_streams_blocked_frame_size) (uint64_t);
290    int
291    (*pf_gen_max_streams_frame) (unsigned char *buf, size_t buf_len,
292                                        enum stream_dir, uint64_t);
293    int
294    (*pf_parse_max_streams_frame) (const unsigned char *buf, size_t buf_len,
295                                        enum stream_dir *, uint64_t *);
296    unsigned
297    (*pf_max_streams_frame_size) (uint64_t);
298    unsigned
299    (*pf_path_chal_frame_size) (void);
300    int
301    (*pf_gen_path_chal_frame) (unsigned char *, size_t, uint64_t chal);
302    unsigned
303    (*pf_path_resp_frame_size) (void);
304    int
305    (*pf_gen_path_resp_frame) (unsigned char *, size_t, uint64_t resp);
306    int
307    (*pf_gen_handshake_done_frame) (unsigned char *buf, size_t buf_len);
308    int
309    (*pf_parse_handshake_done_frame) (const unsigned char *buf, size_t buf_len);
310    unsigned
311    (*pf_handshake_done_frame_size) (void);
312    int
313    (*pf_gen_ack_frequency_frame) (unsigned char *buf, size_t buf_len,
314        uint64_t seqno, uint64_t pack_tol, uint64_t upd_mad, int ignore);
315    int
316    (*pf_parse_ack_frequency_frame) (const unsigned char *buf, size_t buf_len,
317        uint64_t *seqno, uint64_t *pack_tol, uint64_t *upd_mad, int *ignore);
318    unsigned
319    (*pf_ack_frequency_frame_size) (uint64_t seqno, uint64_t pack_tol,
320        uint64_t upd_mad /* Don't need to pass `ignore' */);
321    int
322    (*pf_gen_timestamp_frame) (unsigned char *buf, size_t buf_len, uint64_t);
323    int
324    (*pf_parse_timestamp_frame) (const unsigned char *buf, size_t, uint64_t *);
325    int
326    (*pf_parse_datagram_frame) (const unsigned char *buf, size_t, const void **,
327                                                                    size_t *);
328    int
329    (*pf_gen_datagram_frame) (unsigned char *, size_t bufsz, size_t min_sz,
330        size_t max_sz, ssize_t (*)(struct lsquic_conn *, void *, size_t),
331        struct lsquic_conn *);
332    unsigned
333    (*pf_datagram_frame_size) (size_t);
334};
335
336LSQUIC_EXTERN const struct parse_funcs lsquic_parse_funcs_gquic_Q043;
337LSQUIC_EXTERN const struct parse_funcs lsquic_parse_funcs_gquic_Q046;
338LSQUIC_EXTERN const struct parse_funcs lsquic_parse_funcs_gquic_Q050;
339LSQUIC_EXTERN const struct parse_funcs lsquic_parse_funcs_ietf_v1;
340
341#define select_pf_by_ver(ver) (                                             \
342    (1 << (ver)) & (1 << LSQVER_043)                     ?                  \
343                                         &lsquic_parse_funcs_gquic_Q043 :   \
344    (1 << (ver)) & (1 << LSQVER_046)                            ?           \
345                                         &lsquic_parse_funcs_gquic_Q046 :   \
346    (1 << (ver)) & (1 << LSQVER_050)                            ?           \
347                                         &lsquic_parse_funcs_gquic_Q050 :   \
348    &lsquic_parse_funcs_ietf_v1)
349
350/* This function is gQUIC-version independent */
351int
352lsquic_gquic_parse_packet_in_begin (struct lsquic_packet_in *, size_t length,
353                int is_server, unsigned cid_len, struct packin_parse_state *);
354
355int
356lsquic_Q046_parse_packet_in_short_begin (struct lsquic_packet_in *, size_t length,
357                int is_server, unsigned, struct packin_parse_state *);
358
359int
360lsquic_Q046_parse_packet_in_long_begin (struct lsquic_packet_in *, size_t length,
361                int is_server, unsigned, struct packin_parse_state *);
362
363int
364lsquic_Q050_parse_packet_in_long_begin (struct lsquic_packet_in *, size_t length,
365                int is_server, unsigned, struct packin_parse_state *);
366
367enum quic_frame_type
368lsquic_parse_frame_type_gquic_Q035_thru_Q046 (const unsigned char *, size_t);
369
370extern const enum quic_frame_type lsquic_iquic_byte2type[0x40];
371
372size_t
373lsquic_calc_stream_frame_header_sz_gquic (lsquic_stream_id_t stream_id,
374                                                    uint64_t offset, unsigned);
375
376size_t
377lsquic_gquic_packout_size (const struct lsquic_conn *,
378                                            const struct lsquic_packet_out *);
379
380size_t
381lsquic_gquic_packout_header_size (const struct lsquic_conn *conn,
382                enum packet_out_flags flags, size_t unused, enum header_type);
383
384size_t
385lsquic_gquic_po_header_sz (enum packet_out_flags flags);
386
387size_t
388lsquic_gquic_packout_size (const struct lsquic_conn *,
389                                            const struct lsquic_packet_out *);
390
391size_t
392lsquic_gquic_po_header_sz (enum packet_out_flags flags);
393
394/* This maps two bits as follows:
395 *  00  ->  1
396 *  01  ->  2
397 *  10  ->  4
398 *  11  ->  6
399 *
400 * Assumes that only two low bits are set.
401 */
402#define twobit_to_1246(bits) ((bits) * 2 + !(bits))
403
404/* This maps two bits as follows:
405 *  00  ->  1
406 *  01  ->  2
407 *  10  ->  4
408 *  11  ->  8
409 *
410 * Assumes that only two low bits are set.
411 */
412#define twobit_to_1248(bits) (1 << (bits))
413
414#define ECN_COUNTS_STR  " ECT(0): 01234567879012345678790;" \
415                        " ECT(1): 01234567879012345678790;" \
416                        " CE: 01234567879012345678790"
417#define RANGES_TRUNCATED_STR " ranges truncated! "
418
419#define MAX_ACKI_STR_SZ (256 * (3 /* [-] */ + 20 /* ~0ULL */ * 2) \
420                    + sizeof(ECN_COUNTS_STR) + sizeof(RANGES_TRUNCATED_STR))
421
422void
423lsquic_acki2str (const struct ack_info *acki, char *, size_t);
424
425void
426lsquic_turn_on_fin_Q035_thru_Q046 (unsigned char *);
427
428enum packno_bits
429lsquic_gquic_calc_packno_bits (lsquic_packno_t packno,
430                        lsquic_packno_t least_unacked, uint64_t n_in_flight);
431
432unsigned
433lsquic_gquic_packno_bits2len (enum packno_bits);
434
435int
436lsquic_merge_acks (struct ack_info *dst, const struct ack_info *src);
437
438#endif
439