path: root/include/internal/quic_wire.h

/*
* Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the Apache License 2.0 (the "License").  You may not use
* this file except in compliance with the License.  You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/

#ifndef OSSL_INTERNAL_QUIC_WIRE_H
# define OSSL_INTERNAL_QUIC_WIRE_H
# pragma once

# include "internal/e_os.h"
# include "internal/time.h"
# include "internal/quic_types.h"
# include "internal/packet_quic.h"

# ifndef OPENSSL_NO_QUIC

#  define OSSL_QUIC_FRAME_TYPE_PADDING                0x00
#  define OSSL_QUIC_FRAME_TYPE_PING                   0x01
#  define OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN        0x02
#  define OSSL_QUIC_FRAME_TYPE_ACK_WITH_ECN           0x03
#  define OSSL_QUIC_FRAME_TYPE_RESET_STREAM           0x04
#  define OSSL_QUIC_FRAME_TYPE_STOP_SENDING           0x05
#  define OSSL_QUIC_FRAME_TYPE_CRYPTO                 0x06
#  define OSSL_QUIC_FRAME_TYPE_NEW_TOKEN              0x07
#  define OSSL_QUIC_FRAME_TYPE_MAX_DATA               0x10
#  define OSSL_QUIC_FRAME_TYPE_MAX_STREAM_DATA        0x11
#  define OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_BIDI       0x12
#  define OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_UNI        0x13
#  define OSSL_QUIC_FRAME_TYPE_DATA_BLOCKED           0x14
#  define OSSL_QUIC_FRAME_TYPE_STREAM_DATA_BLOCKED    0x15
#  define OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_BIDI   0x16
#  define OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_UNI    0x17
#  define OSSL_QUIC_FRAME_TYPE_NEW_CONN_ID            0x18
#  define OSSL_QUIC_FRAME_TYPE_RETIRE_CONN_ID         0x19
#  define OSSL_QUIC_FRAME_TYPE_PATH_CHALLENGE         0x1A
#  define OSSL_QUIC_FRAME_TYPE_PATH_RESPONSE          0x1B
#  define OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT   0x1C
#  define OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_APP         0x1D
#  define OSSL_QUIC_FRAME_TYPE_HANDSHAKE_DONE         0x1E

#  define OSSL_QUIC_FRAME_FLAG_STREAM_FIN         0x01
#  define OSSL_QUIC_FRAME_FLAG_STREAM_LEN         0x02
#  define OSSL_QUIC_FRAME_FLAG_STREAM_OFF         0x04
#  define OSSL_QUIC_FRAME_FLAG_STREAM_MASK        ((uint64_t)0x07)

/* Low 3 bits of the type contain flags */
#  define OSSL_QUIC_FRAME_TYPE_STREAM             0x08             /* base ID */
#  define OSSL_QUIC_FRAME_TYPE_STREAM_FIN         \
    (OSSL_QUIC_FRAME_TYPE_STREAM |                \
     OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
#  define OSSL_QUIC_FRAME_TYPE_STREAM_LEN         \
    (OSSL_QUIC_FRAME_TYPE_STREAM |                \
     OSSL_QUIC_FRAME_FLAG_STREAM_LEN)
#  define OSSL_QUIC_FRAME_TYPE_STREAM_LEN_FIN     \
    (OSSL_QUIC_FRAME_TYPE_STREAM |                \
     OSSL_QUIC_FRAME_FLAG_STREAM_LEN |            \
     OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
#  define OSSL_QUIC_FRAME_TYPE_STREAM_OFF         \
    (OSSL_QUIC_FRAME_TYPE_STREAM |                \
     OSSL_QUIC_FRAME_FLAG_STREAM_OFF)
#  define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_FIN     \
    (OSSL_QUIC_FRAME_TYPE_STREAM |                \
     OSSL_QUIC_FRAME_FLAG_STREAM_OFF |            \
     OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
#  define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_LEN     \
    (OSSL_QUIC_FRAME_TYPE_STREAM |                \
     OSSL_QUIC_FRAME_FLAG_STREAM_OFF |            \
     OSSL_QUIC_FRAME_FLAG_STREAM_LEN)
#  define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_LEN_FIN \
    (OSSL_QUIC_FRAME_TYPE_STREAM |                \
     OSSL_QUIC_FRAME_FLAG_STREAM_OFF |            \
     OSSL_QUIC_FRAME_FLAG_STREAM_LEN |            \
     OSSL_QUIC_FRAME_FLAG_STREAM_FIN)

#  define OSSL_QUIC_FRAME_TYPE_IS_STREAM(x) \
    (((x) & ~OSSL_QUIC_FRAME_FLAG_STREAM_MASK) == OSSL_QUIC_FRAME_TYPE_STREAM)
#  define OSSL_QUIC_FRAME_TYPE_IS_ACK(x) \
    (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN)
#  define OSSL_QUIC_FRAME_TYPE_IS_MAX_STREAMS(x) \
    (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_BIDI)
#  define OSSL_QUIC_FRAME_TYPE_IS_STREAMS_BLOCKED(x) \
    (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_BIDI)
#  define OSSL_QUIC_FRAME_TYPE_IS_CONN_CLOSE(x) \
    (((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT)

static ossl_unused ossl_inline int
ossl_quic_frame_type_is_ack_eliciting(uint64_t frame_type)
{
    switch (frame_type) {
    case OSSL_QUIC_FRAME_TYPE_PADDING:
    case OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN:
    case OSSL_QUIC_FRAME_TYPE_ACK_WITH_ECN:
    case OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT:
    case OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_APP:
        return 0;
    default:
        return 1;
    }
}

/* QUIC Transport Parameter Types */
#  define QUIC_TPARAM_ORIG_DCID                           0x00
#  define QUIC_TPARAM_MAX_IDLE_TIMEOUT                    0x01
#  define QUIC_TPARAM_STATELESS_RESET_TOKEN               0x02
#  define QUIC_TPARAM_MAX_UDP_PAYLOAD_SIZE                0x03
#  define QUIC_TPARAM_INITIAL_MAX_DATA                    0x04
#  define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_BIDI_LOCAL  0x05
#  define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_BIDI_REMOTE 0x06
#  define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_UNI         0x07
#  define QUIC_TPARAM_INITIAL_MAX_STREAMS_BIDI            0x08
#  define QUIC_TPARAM_INITIAL_MAX_STREAMS_UNI             0x09
#  define QUIC_TPARAM_ACK_DELAY_EXP                       0x0A
#  define QUIC_TPARAM_MAX_ACK_DELAY                       0x0B
#  define QUIC_TPARAM_DISABLE_ACTIVE_MIGRATION            0x0C
#  define QUIC_TPARAM_PREFERRED_ADDR                      0x0D
#  define QUIC_TPARAM_ACTIVE_CONN_ID_LIMIT                0x0E
#  define QUIC_TPARAM_INITIAL_SCID                        0x0F
#  define QUIC_TPARAM_RETRY_SCID                          0x10

/*
 * QUIC Frame Logical Representations
 * ==================================
 */

/* QUIC Frame: ACK */
typedef struct ossl_quic_ack_range_st {
    /*
     * Represents an inclusive range of packet numbers [start, end].
     * start must be <= end.
     */
    QUIC_PN start, end;
} OSSL_QUIC_ACK_RANGE;

typedef struct ossl_quic_frame_ack_st {
    /*
     * A sequence of packet number ranges [[start, end]...].
     *
     * The ranges must be sorted in descending order, for example:
     *      [ 95, 100]
     *      [ 90,  92]
     *      etc.
     *
     * As such, ack_ranges[0].end is always the highest packet number
     * being acknowledged and ack_ranges[num_ack_ranges-1].start is
     * always the lowest packet number being acknowledged.
     *
     * num_ack_ranges must be greater than zero, as an ACK frame must
     * acknowledge at least one packet number.
     */
    OSSL_QUIC_ACK_RANGE        *ack_ranges;
    size_t                      num_ack_ranges;

    OSSL_TIME                   delay_time;
    uint64_t                    ect0, ect1, ecnce;
    unsigned int                ecn_present : 1;
} OSSL_QUIC_FRAME_ACK;

/* Returns 1 if the given frame contains the given PN. */
int ossl_quic_frame_ack_contains_pn(const OSSL_QUIC_FRAME_ACK *ack, QUIC_PN pn);

/* QUIC Frame: STREAM */
typedef struct ossl_quic_frame_stream_st {
    uint64_t                stream_id;  /* Stream ID */
    uint64_t                offset;     /* Logical offset in stream */
    uint64_t                len;        /* Length of data in bytes */
    const unsigned char    *data;

    /*
     * On encode, this determines whether the len field should be encoded or
     * not. If zero, the len field is not encoded and it is assumed the frame
     * runs to the end of the packet.
     *
     * On decode, this determines whether the frame had an explicitly encoded
     * length. If not set, the frame runs to the end of the packet and len has
     * been set accordingly.
     */
    unsigned int            has_explicit_len : 1;

    /* 1 if this is the end of the stream */
    unsigned int            is_fin : 1;
} OSSL_QUIC_FRAME_STREAM;

/* QUIC Frame: CRYPTO */
typedef struct ossl_quic_frame_crypto_st {
    uint64_t                offset; /* Logical offset in stream */
    uint64_t                len;    /* Length of the data in bytes */
    const unsigned char    *data;
} OSSL_QUIC_FRAME_CRYPTO;

/* QUIC Frame: RESET_STREAM */
typedef struct ossl_quic_frame_reset_stream_st {
    uint64_t    stream_id;
    uint64_t    app_error_code;
    uint64_t    final_size;
} OSSL_QUIC_FRAME_RESET_STREAM;

/* QUIC Frame: STOP_SENDING */
typedef struct ossl_quic_frame_stop_sending_st {
    uint64_t    stream_id;
    uint64_t    app_error_code;
} OSSL_QUIC_FRAME_STOP_SENDING;

/* QUIC Frame: NEW_CONNECTION_ID */
typedef struct ossl_quic_frame_new_conn_id_st {
    uint64_t              seq_num;
    uint64_t              retire_prior_to;
    QUIC_CONN_ID          conn_id;
    unsigned char         stateless_reset_token[16];
} OSSL_QUIC_FRAME_NEW_CONN_ID;

/* QUIC Frame: CONNECTION_CLOSE */
typedef struct ossl_quic_frame_conn_close_st {
    unsigned int    is_app : 1; /* 0: transport error, 1: app error */
    uint64_t        error_code; /* 62-bit transport or app error code */
    uint64_t        frame_type; /* transport errors only */
    char            *reason;    /* UTF-8 string, not necessarily zero-terminated */
    size_t          reason_len; /* Length of reason in bytes */
} OSSL_QUIC_FRAME_CONN_CLOSE;

/*
 * QUIC Wire Format Encoding
 * =========================
 *
 * These functions return 1 on success and 0 on failure.
 */

/*
 * Encodes zero or more QUIC PADDING frames to the packet writer. Each PADDING
 * frame consumes one byte; num_bytes specifies the number of bytes of padding
 * to write.
 */
int ossl_quic_wire_encode_padding(WPACKET *pkt, size_t num_bytes);

/*
 * Encodes a QUIC PING frame to the packet writer. This frame type takes
 * no arguments.
*/
int ossl_quic_wire_encode_frame_ping(WPACKET *pkt);

/*
 * Encodes a QUIC ACK frame to the packet writer, given a logical representation
 * of the ACK frame.
 *
 * The ACK ranges passed must be sorted in descending order.
 *
 * The logical representation stores a list of packet number ranges. The wire
 * encoding is slightly different and stores the first range in the list
 * in a different manner.
 *
 * The ack_delay_exponent argument specifies the index of a power of two by
 * which the ack->ack_delay field is be divided. This exponent value must match
 * the value used when decoding.
 */
int ossl_quic_wire_encode_frame_ack(WPACKET *pkt,
                                    uint32_t ack_delay_exponent,
                                    const OSSL_QUIC_FRAME_ACK *ack);

/*
 * Encodes a QUIC RESET_STREAM frame to the packet writer, given a logical
 * representation of the RESET_STREAM frame.
 */
int ossl_quic_wire_encode_frame_reset_stream(WPACKET *pkt,
                                             const OSSL_QUIC_FRAME_RESET_STREAM *f);

/*
 * Encodes a QUIC STOP_SENDING frame to the packet writer, given a logical
 * representation of the STOP_SENDING frame.
 */
int ossl_quic_wire_encode_frame_stop_sending(WPACKET *pkt,
                                             const OSSL_QUIC_FRAME_STOP_SENDING *f);

/*
 * Encodes a QUIC CRYPTO frame header to the packet writer.
 *
 * To create a well-formed frame, the data written using this function must be
 * immediately followed by f->len bytes of data.
 */
int ossl_quic_wire_encode_frame_crypto_hdr(WPACKET *hdr,
                                           const OSSL_QUIC_FRAME_CRYPTO *f);

/*
 * Returns the number of bytes which will be required to encode the given
 * CRYPTO frame header. Does not include the payload bytes in the count.
 * Returns 0 if input is invalid.
 */
size_t ossl_quic_wire_get_encoded_frame_len_crypto_hdr(const OSSL_QUIC_FRAME_CRYPTO *f);

/*
 * Encodes a QUIC CRYPTO frame to the packet writer.
 *
 * This function returns a pointer to a buffer of f->len bytes which the caller
 * should fill however it wishes. If f->data is non-NULL, it is automatically
 * copied to the target buffer, otherwise the caller must fill the returned
 * buffer. Returns NULL on failure.
 */
void *ossl_quic_wire_encode_frame_crypto(WPACKET *pkt,
                                         const <