include/internal/quic_wire.h

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