1 /*
2 * Copyright 2022-2023 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_INTERNAL_QUIC_WIRE_H
11 # define OSSL_INTERNAL_QUIC_WIRE_H
12 # pragma once
13
14 # include "internal/e_os.h"
15 # include "internal/time.h"
16 # include "internal/quic_types.h"
17 # include "internal/packet_quic.h"
18
19 # ifndef OPENSSL_NO_QUIC
20
21 # define OSSL_QUIC_FRAME_TYPE_PADDING 0x00
22 # define OSSL_QUIC_FRAME_TYPE_PING 0x01
23 # define OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN 0x02
24 # define OSSL_QUIC_FRAME_TYPE_ACK_WITH_ECN 0x03
25 # define OSSL_QUIC_FRAME_TYPE_RESET_STREAM 0x04
26 # define OSSL_QUIC_FRAME_TYPE_STOP_SENDING 0x05
27 # define OSSL_QUIC_FRAME_TYPE_CRYPTO 0x06
28 # define OSSL_QUIC_FRAME_TYPE_NEW_TOKEN 0x07
29 # define OSSL_QUIC_FRAME_TYPE_MAX_DATA 0x10
30 # define OSSL_QUIC_FRAME_TYPE_MAX_STREAM_DATA 0x11
31 # define OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_BIDI 0x12
32 # define OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_UNI 0x13
33 # define OSSL_QUIC_FRAME_TYPE_DATA_BLOCKED 0x14
34 # define OSSL_QUIC_FRAME_TYPE_STREAM_DATA_BLOCKED 0x15
35 # define OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_BIDI 0x16
36 # define OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_UNI 0x17
37 # define OSSL_QUIC_FRAME_TYPE_NEW_CONN_ID 0x18
38 # define OSSL_QUIC_FRAME_TYPE_RETIRE_CONN_ID 0x19
39 # define OSSL_QUIC_FRAME_TYPE_PATH_CHALLENGE 0x1A
40 # define OSSL_QUIC_FRAME_TYPE_PATH_RESPONSE 0x1B
41 # define OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT 0x1C
42 # define OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_APP 0x1D
43 # define OSSL_QUIC_FRAME_TYPE_HANDSHAKE_DONE 0x1E
44
45 # define OSSL_QUIC_FRAME_FLAG_STREAM_FIN 0x01
46 # define OSSL_QUIC_FRAME_FLAG_STREAM_LEN 0x02
47 # define OSSL_QUIC_FRAME_FLAG_STREAM_OFF 0x04
48 # define OSSL_QUIC_FRAME_FLAG_STREAM_MASK ((uint64_t)0x07)
49
50 /* Low 3 bits of the type contain flags */
51 # define OSSL_QUIC_FRAME_TYPE_STREAM 0x08 /* base ID */
52 # define OSSL_QUIC_FRAME_TYPE_STREAM_FIN \
53 (OSSL_QUIC_FRAME_TYPE_STREAM | \
54 OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
55 # define OSSL_QUIC_FRAME_TYPE_STREAM_LEN \
56 (OSSL_QUIC_FRAME_TYPE_STREAM | \
57 OSSL_QUIC_FRAME_FLAG_STREAM_LEN)
58 # define OSSL_QUIC_FRAME_TYPE_STREAM_LEN_FIN \
59 (OSSL_QUIC_FRAME_TYPE_STREAM | \
60 OSSL_QUIC_FRAME_FLAG_STREAM_LEN | \
61 OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
62 # define OSSL_QUIC_FRAME_TYPE_STREAM_OFF \
63 (OSSL_QUIC_FRAME_TYPE_STREAM | \
64 OSSL_QUIC_FRAME_FLAG_STREAM_OFF)
65 # define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_FIN \
66 (OSSL_QUIC_FRAME_TYPE_STREAM | \
67 OSSL_QUIC_FRAME_FLAG_STREAM_OFF | \
68 OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
69 # define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_LEN \
70 (OSSL_QUIC_FRAME_TYPE_STREAM | \
71 OSSL_QUIC_FRAME_FLAG_STREAM_OFF | \
72 OSSL_QUIC_FRAME_FLAG_STREAM_LEN)
73 # define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_LEN_FIN \
74 (OSSL_QUIC_FRAME_TYPE_STREAM | \
75 OSSL_QUIC_FRAME_FLAG_STREAM_OFF | \
76 OSSL_QUIC_FRAME_FLAG_STREAM_LEN | \
77 OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
78
79 # define OSSL_QUIC_FRAME_TYPE_IS_STREAM(x) \
80 (((x) & ~OSSL_QUIC_FRAME_FLAG_STREAM_MASK) == OSSL_QUIC_FRAME_TYPE_STREAM)
81 # define OSSL_QUIC_FRAME_TYPE_IS_ACK(x) \
82 (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN)
83 # define OSSL_QUIC_FRAME_TYPE_IS_MAX_STREAMS(x) \
84 (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_BIDI)
85 # define OSSL_QUIC_FRAME_TYPE_IS_STREAMS_BLOCKED(x) \
86 (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_BIDI)
87 # define OSSL_QUIC_FRAME_TYPE_IS_CONN_CLOSE(x) \
88 (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT)
89
90 const char *ossl_quic_frame_type_to_string(uint64_t frame_type);
91
92 static ossl_unused ossl_inline int
ossl_quic_frame_type_is_ack_eliciting(uint64_t frame_type)93 ossl_quic_frame_type_is_ack_eliciting(uint64_t frame_type)
94 {
95 switch (frame_type) {
96 case OSSL_QUIC_FRAME_TYPE_PADDING:
97 case OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN:
98 case OSSL_QUIC_FRAME_TYPE_ACK_WITH_ECN:
99 case OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT:
100 case OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_APP:
101 return 0;
102 default:
103 return 1;
104 }
105 }
106
107 /* QUIC Transport Parameter Types */
108 # define QUIC_TPARAM_ORIG_DCID 0x00
109 # define QUIC_TPARAM_MAX_IDLE_TIMEOUT 0x01
110 # define QUIC_TPARAM_STATELESS_RESET_TOKEN 0x02
111 # define QUIC_TPARAM_MAX_UDP_PAYLOAD_SIZE 0x03
112 # define QUIC_TPARAM_INITIAL_MAX_DATA 0x04
113 # define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_BIDI_LOCAL 0x05
114 # define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_BIDI_REMOTE 0x06
115 # define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_UNI 0x07
116 # define QUIC_TPARAM_INITIAL_MAX_STREAMS_BIDI 0x08
117 # define QUIC_TPARAM_INITIAL_MAX_STREAMS_UNI 0x09
118 # define QUIC_TPARAM_ACK_DELAY_EXP 0x0A
119 # define QUIC_TPARAM_MAX_ACK_DELAY 0x0B
120 # define QUIC_TPARAM_DISABLE_ACTIVE_MIGRATION 0x0C
121 # define QUIC_TPARAM_PREFERRED_ADDR 0x0D
122 # define QUIC_TPARAM_ACTIVE_CONN_ID_LIMIT 0x0E
123 # define QUIC_TPARAM_INITIAL_SCID 0x0F
124 # define QUIC_TPARAM_RETRY_SCID 0x10
125
126 /*
127 * QUIC Frame Logical Representations
128 * ==================================
129 */
130
131 /* QUIC Frame: ACK */
132 typedef struct ossl_quic_ack_range_st {
133 /*
134 * Represents an inclusive range of packet numbers [start, end].
135 * start must be <= end.
136 */
137 QUIC_PN start, end;
138 } OSSL_QUIC_ACK_RANGE;
139
140 typedef struct ossl_quic_frame_ack_st {
141 /*
142 * A sequence of packet number ranges [[start, end]...].
143 *
144 * The ranges must be sorted in descending order, for example:
145 * [ 95, 100]
146 * [ 90, 92]
147 * etc.
148 *
149 * As such, ack_ranges[0].end is always the highest packet number
150 * being acknowledged and ack_ranges[num_ack_ranges-1].start is
151 * always the lowest packet number being acknowledged.
152 *
153 * num_ack_ranges must be greater than zero, as an ACK frame must
154 * acknowledge at least one packet number.
155 */
156 OSSL_QUIC_ACK_RANGE *ack_ranges;
157 size_t num_ack_ranges;
158
159 OSSL_TIME delay_time;
160 uint64_t ect0, ect1, ecnce;
161 unsigned int ecn_present : 1;
162 } OSSL_QUIC_FRAME_ACK;
163
164 /* Returns 1 if the given frame contains the given PN. */
165 int ossl_quic_frame_ack_contains_pn(const OSSL_QUIC_FRAME_ACK *ack, QUIC_PN pn);
166
167 /* QUIC Frame: STREAM */
168 typedef struct ossl_quic_frame_stream_st {
169 uint64_t stream_id; /* Stream ID */
170 uint64_t offset; /* Logical offset in stream */
171 uint64_t len; /* Length of data in bytes */
172 const unsigned char *data;
173
174 /*
175 * On encode, this determines whether the len field should be encoded or
176 * not. If zero, the len field is not encoded and it is assumed the frame
177 * runs to the end of the packet.
178 *
179 * On decode, this determines whether the frame had an explicitly encoded
180 * length. If not set, the frame runs to the end of the packet and len has
181 * been set accordingly.
182 */
183 unsigned int has_explicit_len : 1;
184
185 /* 1 if this is the end of the stream */
186 unsigned int is_fin : 1;
187 } OSSL_QUIC_FRAME_STREAM;
188
189 /* QUIC Frame: CRYPTO */
190 typedef struct ossl_quic_frame_crypto_st {
191 uint64_t offset; /* Logical offset in stream */
192 uint64_t len; /* Length of the data in bytes */
193 const unsigned char *data;
194 } OSSL_QUIC_FRAME_CRYPTO;
195
196 /* QUIC Frame: RESET_STREAM */
197 typedef struct ossl_quic_frame_reset_stream_st {
198 uint64_t stream_id;
199 uint64_t app_error_code;
200 uint64_t final_size;
201 } OSSL_QUIC_FRAME_RESET_STREAM;
202
203 /* QUIC Frame: STOP_SENDING */
204 typedef struct ossl_quic_frame_stop_sending_st {
205 uint64_t stream_id;
206 uint64_t app_error_code;
207 } OSSL_QUIC_FRAME_STOP_SENDING;
208
209 /* QUIC Frame: NEW_CONNECTION_ID */
210 typedef struct ossl_quic_frame_new_conn_id_st {
211 uint64_t seq_num;
212 uint64_t retire_prior_to;
213 QUIC_CONN_ID conn_id;
214 QUIC_STATELESS_RESET_TOKEN stateless_reset;
215 } OSSL_QUIC_FRAME_NEW_CONN_ID;
216
217 /* QUIC Frame: CONNECTION_CLOSE */
218 typedef struct ossl_quic_frame_conn_close_st {
219 unsigned int is_app : 1; /* 0: transport error, 1: app error */
220 uint64_t error_code; /* 62-bit transport or app error code */
221 uint64_t frame_type; /* transport errors only */
222 char *reason; /* UTF-8 string, not necessarily zero-terminated */
223 size_t reason_len; /* Length of reason in bytes */
224 } OSSL_QUIC_FRAME_CONN_CLOSE;
225
226 /*
227 * QUIC Wire Format Encoding
228 * =========================
229 *
230 * These functions return 1 on success and 0 on failure.
231 */
232
233 /*
234 * Encodes zero or more QUIC PADDING frames to the packet writer. Each PADDING
235 * frame consumes one byte; num_bytes specifies the number of bytes of padding
236 * to write.
237 */
238 int ossl_quic_wire_encode_padding(WPACKET *pkt, size_t num_bytes);
239
240 /*
241 * Encodes a QUIC PING frame to the packet writer. This frame type takes
242 * no arguments.
243 */
244 int ossl_quic_wire_encode_frame_ping(WPACKET *pkt);
245
246 /*
247 * Encodes a QUIC ACK frame to the packet writer, given a logical representation
248 * of the ACK frame.
249 *
250 * The ACK ranges passed must be sorted in descending order.
251 *
252 * The logical representation stores a list of packet number ranges. The wire
253 * encoding is slightly different and stores the first range in the list
254 * in a different manner.
255 *
256 * The ack_delay_exponent argument specifies the index of a power of two by
257 * which the ack->ack_delay field is be divided. This exponent value must match
258 * the value used when decoding.
259 */
260 int ossl_quic_wire_encode_frame_ack(WPACKET *pkt,
261 uint32_t ack_delay_exponent,
262 const OSSL_QUIC_FRAME_ACK *ack);
263
264 /*
265 * Encodes a QUIC RESET_STREAM frame to the packet writer, given a logical
266 * representation of the RESET_STREAM frame.
267 */
268 int ossl_quic_wire_encode_frame_reset_stream(WPACKET *pkt,
269 const OSSL_QUIC_FRAME_RESET_STREAM *f);
270
271 /*
272 * Encodes a QUIC STOP_SENDING frame to the packet writer, given a logical
273 * representation of the STOP_SENDING frame.
274 */
275 int ossl_quic_wire_encode_frame_stop_sending(WPACKET *pkt,
276 const OSSL_QUIC_FRAME_STOP_SENDING *f);
277
278 /*
279 * Encodes a QUIC CRYPTO frame header to the packet writer.
280 *
281 * To create a well-formed frame, the data written using this function must be
282 * immediately followed by f->len bytes of data.
283 */
284 int ossl_quic_wire_encode_frame_crypto_hdr(WPACKET *hdr,
285 const OSSL_QUIC_FRAME_CRYPTO *f);
286
287 /*
288 * Returns the number of bytes which will be required to encode the given
289 * CRYPTO frame header. Does not include the payload bytes in the count.
290 * Returns 0 if input is invalid.
291 */
292 size_t ossl_quic_wire_get_encoded_frame_len_crypto_hdr(const OSSL_QUIC_FRAME_CRYPTO *f);
293
294 /*
295 * Encodes a QUIC CRYPTO frame to the packet writer.
296 *
297 * This function returns a pointer to a buffer of f->len bytes which the caller
298 * should fill however it wishes. If f->data is non-NULL, it is automatically
299 * copied to the target buffer, otherwise the caller must fill the returned
300 * buffer. Returns NULL on failure.
301 */
302 void *ossl_quic_wire_encode_frame_crypto(WPACKET *pkt,
303 const OSSL_QUIC_FRAME_CRYPTO *f);
304
305 /*
306 * Encodes a QUIC NEW_TOKEN frame to the packet writer.
307 */
308 int ossl_quic_wire_encode_frame_new_token(WPACKET *pkt,
309 const unsigned char *token,
310 size_t token_len);
311
312 /*
313 * Encodes a QUIC STREAM frame's header to the packet writer. The f->stream_id,
314 * f->offset and f->len fields are the values for the respective Stream ID,
315 * Offset and Length fields.
316 *
317 * If f->is_fin is non-zero, the frame is marked as the final frame in the
318 * stream.
319 *
320 * If f->has_explicit_len is zerro, the frame is assumed to be the final frame
321 * in the packet, which the caller is responsible for ensuring; the Length
322 * field is then omitted.
323 *
324 * To create a well-formed frame, the data written using this function must be
325 * immediately followed by f->len bytes of stream data.
326 */
327 int ossl_quic_wire_encode_frame_stream_hdr(WPACKET *pkt,
328 const OSSL_QUIC_FRAME_STREAM *f);
329
330 /*
331 * Returns the number of bytes which will be required to encode the given
332 * STREAM frame header. Does not include the payload bytes in the count.
333 * Returns 0 if input is invalid.
334 */
335 size_t ossl_quic_wire_get_encoded_frame_len_stream_hdr(const OSSL_QUIC_FRAME_STREAM *f);
336
337 /*
338 * Functions similarly to ossl_quic_wire_encode_frame_stream_hdr, but it also
339 * allocates space for f->len bytes of data after the header, creating a
340 * well-formed QUIC STREAM frame in one call.
341 *
342 * A pointer to the bytes allocated for the framme payload is returned,
343 * which the caller can fill however it wishes. If f->data is non-NULL,
344 * it is automatically copied to the target buffer, otherwise the caller
345 * must fill the returned buffer. Returns NULL on failure.
346 */
347 void *ossl_quic_wire_encode_frame_stream(WPACKET *pkt,
348 const OSSL_QUIC_FRAME_STREAM *f);
349
350 /*
351 * Encodes a QUIC MAX_DATA frame to the packet writer.
352 */
353 int ossl_quic_wire_encode_frame_max_data(WPACKET *pkt,
354 uint64_t max_data);
355
356 /*
357 * Encodes a QUIC MAX_STREAM_DATA frame to the packet writer.
358 */
359 int ossl_quic_wire_encode_frame_max_stream_data(WPACKET *pkt,
360 uint64_t stream_id,
361 uint64_t max_data);
362
363 /*
364 * Encodes a QUIC MAX_STREAMS frame to the packet writer.
365 *
366 * If is_uni is 0, the count specifies the maximum number of
367 * bidirectional streams; else it specifies the maximum number of unidirectional
368 * streams.
369 */
370 int ossl_quic_wire_encode_frame_max_streams(WPACKET *pkt,
371 char is_uni,
372 uint64_t max_streams);
373
374 /*
375 * Encodes a QUIC DATA_BLOCKED frame to the packet writer.
376 */
377 int ossl_quic_wire_encode_frame_data_blocked(WPACKET *pkt,
378 uint64_t max_data);
379
380 /*
381 * Encodes a QUIC STREAM_DATA_BLOCKED frame to the packet writer.
382 */
383 int ossl_quic_wire_encode_frame_stream_data_blocked(WPACKET *pkt,
384 uint64_t stream_id,
385 uint64_t max_stream_data);
386 /*
387 * Encodes a QUIC STREAMS_BLOCKED frame to the packet writer.
388 *
389 * If is_uni is 0, the count specifies the maximum number of
390 * bidirectional streams; else it specifies the maximum number of unidirectional
391 * streams.
392 */
393 int ossl_quic_wire_encode_frame_streams_blocked(WPACKET *pkt,
394 char is_uni,
395 uint64_t max_streams);
396
397 /*
398 * Encodes a QUIC NEW_CONNECTION_ID frame to the packet writer, given a logical
399 * representation of the NEW_CONNECTION_ID frame.
400 *
401 * The buffer pointed to by the conn_id field must be valid for the duration of
402 * the call.
403 */
404 int ossl_quic_wire_encode_frame_new_conn_id(WPACKET *pkt,
405 const OSSL_QUIC_FRAME_NEW_CONN_ID *f);
406
407 /*
408 * Encodes a QUIC RETIRE_CONNECTION_ID frame to the packet writer.
409 */
410 int ossl_quic_wire_encode_frame_retire_conn_id(WPACKET *pkt,
411 uint64_t seq_num);
412
413 /*
414 * Encodes a QUIC PATH_CHALLENGE frame to the packet writer.
415 */
416 int ossl_quic_wire_encode_frame_path_challenge(WPACKET *pkt,
417 uint64_t data);
418
419 /*
420 * Encodes a QUIC PATH_RESPONSE frame to the packet writer.
421 */
422 int ossl_quic_wire_encode_frame_path_response(WPACKET *pkt,
423 uint64_t data);
424
425 /*
426 * Encodes a QUIC CONNECTION_CLOSE frame to the packet writer, given a logical
427 * representation of the CONNECTION_CLOSE frame.
428 *
429 * The reason field may be NULL, in which case no reason is encoded. If the
430 * reason field is non-NULL, it must point to a valid UTF-8 string and
431 * reason_len must be set to the length of the reason string in bytes. The
432 * reason string need not be zero terminated.
433 */
434 int ossl_quic_wire_encode_frame_conn_close(WPACKET *pkt,
435 const OSSL_QUIC_FRAME_CONN_CLOSE *f);
436
437 /*
438 * Encodes a QUIC HANDSHAKE_DONE frame to the packet writer. This frame type
439 * takes no arguiments.
440 */
441 int ossl_quic_wire_encode_frame_handshake_done(WPACKET *pkt);
442
443 /*
444 * Encodes a QUIC transport parameter TLV with the given ID into the WPACKET.
445 * The payload is an arbitrary buffer.
446 *
447 * If value is non-NULL, the value is copied into the packet.
448 * If it is NULL, value_len bytes are allocated for the payload and the caller
449 * should fill the buffer using the returned pointer.
450 *
451 * Returns a pointer to the start of the payload on success, or NULL on failure.
452 */
453 unsigned char *ossl_quic_wire_encode_transport_param_bytes(WPACKET *pkt,
454 uint64_t id,
455 const unsigned char *value,
456 size_t value_len);
457
458 /*
459 * Encodes a QUIC transport parameter TLV with the given ID into the WPACKET.
460 * The payload is a QUIC variable-length integer with the given value.
461 */
462 int ossl_quic_wire_encode_transport_param_int(WPACKET *pkt,
463 uint64_t id,
464 uint64_t value);
465
466 /*
467 * Encodes a QUIC transport parameter TLV with a given ID into the WPACKET.
468 * The payload is a QUIC connection ID.
469 */
470 int ossl_quic_wire_encode_transport_param_cid(WPACKET *wpkt,
471 uint64_t id,
472 const QUIC_CONN_ID *cid);
473
474 /*
475 * QUIC Wire Format Decoding
476 * =========================
477 *
478 * These functions return 1 on success or 0 for failure. Typical reasons
479 * why these functions may fail include:
480 *
481 * - A frame decode function is called but the frame in the PACKET's buffer
482 * is not of the correct type.
483 *
484 * - A variable-length field in the encoded frame appears to exceed the bounds
485 * of the PACKET's buffer.
486 *
487 * These functions should be called with the PACKET pointing to the start of the
488 * frame (including the initial type field), and consume an entire frame
489 * including its type field. The expectation is that the caller will have
490 * already discerned the frame type using ossl_quic_wire_peek_frame_header().
491 */
492
493 /*
494 * Decodes the type field header of a QUIC frame (without advancing the current
495 * position). This can be used to determine the frame type and determine which
496 * frame decoding function to call.
497 */
498 int ossl_quic_wire_peek_frame_header(PACKET *pkt, uint64_t *type,
499 int *was_minimal);
500
501 /*
502 * Like ossl_quic_wire_peek_frame_header, but advances the current position
503 * so that the type field is consumed. For advanced use only.
504 */
505 int ossl_quic_wire_skip_frame_header(PACKET *pkt, uint64_t *type);
506
507 /*
508 * Determines how many ranges are needed to decode a QUIC ACK frame.
509 *
510 * The number of ranges which must be allocated before the call to
511 * ossl_quic_wire_decode_frame_ack is written to *total_ranges.
512 *
513 * The PACKET is not advanced.
514 */
515 int ossl_quic_wire_peek_frame_ack_num_ranges(const PACKET *pkt,
516 uint64_t *total_ranges);
517
518 /*
519 * Decodes a QUIC ACK frame. The ack_ranges field of the passed structure should
520 * point to a preallocated array of ACK ranges and the num_ack_ranges field
521 * should specify the length of allocation.
522 *
523 * *total_ranges is written with the number of ranges in the decoded frame,
524 * which may be greater than the number of ranges which were decoded (i.e. if
525 * num_ack_ranges was too small to decode all ranges).
526 *
527 * On success, this function modifies the num_ack_ranges field to indicate the
528 * number of ranges in the decoded frame. This is the number of entries in the
529 * ACK ranges array written by this function; any additional entries are not
530 * modified.
531 *
532 * If the number of ACK ranges in the decoded frame exceeds that in
533 * num_ack_ranges, as many ACK ranges as possible are decoded into the range
534 * array. The caller can use the value written to *total_ranges to detect this
535 * condition, as *total_ranges will exceed num_ack_ranges.
536 *
537 * If ack is NULL, the frame is still decoded, but only *total_ranges is
538 * written. This can be used to determine the number of ranges which must be
539 * allocated.
540 *
541 * The ack_delay_exponent argument specifies the index of a power of two used to
542 * decode the ack_delay field. This must match the ack_delay_exponent value used
543 * to encode the frame.
544 */
545 int ossl_quic_wire_decode_frame_ack(PACKET *pkt,
546 uint32_t ack_delay_exponent,
547 OSSL_QUIC_FRAME_ACK *ack,
548 uint64_t *total_ranges);
549
550 /*
551 * Decodes a QUIC RESET_STREAM frame.
552 */
553 int ossl_quic_wire_decode_frame_reset_stream(PACKET *pkt,
554 OSSL_QUIC_FRAME_RESET_STREAM *f);
555
556 /*
557 * Decodes a QUIC STOP_SENDING frame.
558 */
559 int ossl_quic_wire_decode_frame_stop_sending(PACKET *pkt,
560 OSSL_QUIC_FRAME_STOP_SENDING *f);
561
562 /*
563 * Decodes a QUIC CRYPTO frame.
564 *
565 * f->data is set to point inside the packet buffer inside the PACKET, therefore
566 * it is safe to access for as long as the packet buffer exists. If nodata is
567 * set to 1 then reading the PACKET stops after the frame header and f->data is
568 * set to NULL.
569 */
570 int ossl_quic_wire_decode_frame_crypto(PACKET *pkt, int nodata,
571 OSSL_QUIC_FRAME_CRYPTO *f);
572
573 /*
574 * Decodes a QUIC NEW_TOKEN frame. *token is written with a pointer to the token
575 * bytes and *token_len is written with the length of the token in bytes.
576 */
577 int ossl_quic_wire_decode_frame_new_token(PACKET *pkt,
578 const unsigned char **token,
579 size_t *token_len);
580
581 /*
582 * Decodes a QUIC STREAM frame.
583 *
584 * If nodata is set to 1 then reading the PACKET stops after the frame header
585 * and f->data is set to NULL. In this case f->len will also be 0 in the event
586 * that "has_explicit_len" is 0.
587 *
588 * If the frame did not contain an offset field, f->offset is set to 0, as the
589 * absence of an offset field is equivalent to an offset of 0.
590 *
591 * If the frame contained a length field, f->has_explicit_len is set to 1 and
592 * the length of the data is placed in f->len. This function ensures that the
593 * length does not exceed the packet buffer, thus it is safe to access f->data.
594 *
595 * If the frame did not contain a length field, this means that the frame runs
596 * until the end of the packet. This function sets f->has_explicit_len to zero,
597 * and f->len to the amount of data remaining in the input buffer. Therefore,
598 * this function should be used with a PACKET representing a single packet (and
599 * not e.g. multiple packets).
600 *
601 * Note also that this means f->len is always valid after this function returns
602 * successfully, regardless of the value of f->has_explicit_len.
603 *
604 * f->data points inside the packet buffer inside the PACKET, therefore it is
605 * safe to access for as long as the packet buffer exists.
606 *
607 * f->is_fin is set according to whether the frame was marked as ending the
608 * stream.
609 */
610 int ossl_quic_wire_decode_frame_stream(PACKET *pkt, int nodata,
611 OSSL_QUIC_FRAME_STREAM *f);
612
613 /*
614 * Decodes a QUIC MAX_DATA frame. The Maximum Data field is written to
615 * *max_data.
616 */
617 int ossl_quic_wire_decode_frame_max_data(PACKET *pkt,
618 uint64_t *max_data);
619
620 /*
621 * Decodes a QUIC MAX_STREAM_DATA frame. The Stream ID is written to *stream_id
622 * and Maximum Stream Data field is written to *max_stream_data.
623 */
624 int ossl_quic_wire_decode_frame_max_stream_data(PACKET *pkt,
625 uint64_t *stream_id,
626 uint64_t *max_stream_data);
627 /*
628 * Decodes a QUIC MAX_STREAMS frame. The Maximum Streams field is written to
629 * *max_streams.
630 *
631 * Whether the limit concerns bidirectional streams or unidirectional streams is
632 * denoted by the frame type; the caller should examine the frame type to
633 * determine this.
634 */
635 int ossl_quic_wire_decode_frame_max_streams(PACKET *pkt,
636 uint64_t *max_streams);
637
638 /*
639 * Decodes a QUIC DATA_BLOCKED frame. The Maximum Data field is written to
640 * *max_data.
641 */
642 int ossl_quic_wire_decode_frame_data_blocked(PACKET *pkt,
643 uint64_t *max_data);
644
645 /*
646 * Decodes a QUIC STREAM_DATA_BLOCKED frame. The Stream ID and Maximum Stream
647 * Data fields are written to *stream_id and *max_stream_data respectively.
648 */
649 int ossl_quic_wire_decode_frame_stream_data_blocked(PACKET *pkt,
650 uint64_t *stream_id,
651 uint64_t *max_stream_data);
652
653 /*
654 * Decodes a QUIC STREAMS_BLOCKED frame. The Maximum Streams field is written to
655 * *max_streams.
656 *
657 * Whether the limit concerns bidirectional streams or unidirectional streams is
658 * denoted by the frame type; the caller should examine the frame type to
659 * determine this.
660 */
661 int ossl_quic_wire_decode_frame_streams_blocked(PACKET *pkt,
662 uint64_t *max_streams);
663
664
665 /*
666 * Decodes a QUIC NEW_CONNECTION_ID frame. The logical representation of the
667 * frame is written to *f.
668 *
669 * The conn_id field is set to point to the connection ID string inside the
670 * packet buffer; it is therefore valid for as long as the PACKET's buffer is
671 * valid. The conn_id_len field is set to the length of the connection ID string
672 * in bytes.
673 */
674 int ossl_quic_wire_decode_frame_new_conn_id(PACKET *pkt,
675 OSSL_QUIC_FRAME_NEW_CONN_ID *f);
676
677 /*
678 * Decodes a QUIC RETIRE_CONNECTION_ID frame. The Sequence Number field
679 * is written to *seq_num.
680 */
681 int ossl_quic_wire_decode_frame_retire_conn_id(PACKET *pkt,
682 uint64_t *seq_num);
683
684 /*
685 * Decodes a QUIC PATH_CHALLENGE frame. The Data field is written to *data.
686 */
687 int ossl_quic_wire_decode_frame_path_challenge(PACKET *pkt,
688 uint64_t *data);
689
690 /*
691 * Decodes a QUIC PATH_CHALLENGE frame. The Data field is written to *data.
692 */
693 int ossl_quic_wire_decode_frame_path_response(PACKET *pkt,
694 uint64_t *data);
695
696 /*
697 * Decodes a QUIC CONNECTION_CLOSE frame. The logical representation
698 * of the frame is written to *f.
699 *
700 * The reason field is set to point to the UTF-8 reason string inside
701 * the packet buffer; it is therefore valid for as long as the PACKET's
702 * buffer is valid. The reason_len field is set to the length of the
703 * reason string in bytes.
704 *
705 * IMPORTANT: The reason string is not zero-terminated.
706 *
707 * Returns 1 on success or 0 on failure.
708 */
709 int ossl_quic_wire_decode_frame_conn_close(PACKET *pkt,
710 OSSL_QUIC_FRAME_CONN_CLOSE *f);
711
712 /*
713 * Decodes one or more PADDING frames. PADDING frames have no arguments.
714 *
715 * Returns the number of PADDING frames decoded or 0 on error.
716 */
717 size_t ossl_quic_wire_decode_padding(PACKET *pkt);
718
719 /*
720 * Decodes a PING frame. The frame has no arguments.
721 */
722 int ossl_quic_wire_decode_frame_ping(PACKET *pkt);
723
724 /*
725 * Decodes a HANDSHAKE_DONE frame. The frame has no arguments.
726 */
727 int ossl_quic_wire_decode_frame_handshake_done(PACKET *pkt);
728
729 /*
730 * Peeks at the ID of the next QUIC transport parameter TLV in the stream.
731 * The ID is written to *id.
732 */
733 int ossl_quic_wire_peek_transport_param(PACKET *pkt, uint64_t *id);
734
735 /*
736 * Decodes a QUIC transport parameter TLV. A pointer to the value buffer is
737 * returned on success. This points inside the PACKET's buffer and is therefore
738 * valid as long as the PACKET's buffer is valid.
739 *
740 * The transport parameter ID is written to *id (if non-NULL) and the length of
741 * the payload in bytes is written to *len.
742 *
743 * Returns NULL on failure.
744 */
745 const unsigned char *ossl_quic_wire_decode_transport_param_bytes(PACKET *pkt,
746 uint64_t *id,
747 size_t *len);
748
749 /*
750 * Decodes a QUIC transport parameter TLV containing a variable-length integer.
751 *
752 * The transport parameter ID is written to *id (if non-NULL) and the value is
753 * written to *value.
754 */
755 int ossl_quic_wire_decode_transport_param_int(PACKET *pkt,
756 uint64_t *id,
757 uint64_t *value);
758
759 /*
760 * Decodes a QUIC transport parameter TLV containing a connection ID.
761 *
762 * The transport parameter ID is written to *id (if non-NULL) and the value is
763 * written to *value.
764 */
765 int ossl_quic_wire_decode_transport_param_cid(PACKET *pkt,
766 uint64_t *id,
767 QUIC_CONN_ID *cid);
768
769 /*
770 * Decodes a QUIC transport parameter TLV containing a preferred_address.
771 */
772 typedef struct quic_preferred_addr_st {
773 uint16_t ipv4_port, ipv6_port;
774 unsigned char ipv4[4], ipv6[16];
775 QUIC_STATELESS_RESET_TOKEN stateless_reset;
776 QUIC_CONN_ID cid;
777 } QUIC_PREFERRED_ADDR;
778
779 int ossl_quic_wire_decode_transport_param_preferred_addr(PACKET *pkt,
780 QUIC_PREFERRED_ADDR *p);
781
782 # endif
783
784 #endif
785
