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 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