lsquic_trans_params.h revision 06b2a236 
1/* Copyright (c) 2017 - 2021 LiteSpeed Technologies Inc.  See LICENSE. */
2/*
3 * lsquic_trans_params.h -- Transport parameters types and functions.
4 */
5
6#ifndef LSQUIC_TRANS_PARAMS_H
7#define LSQUIC_TRANS_PARAMS_H 1
8
9/* Transport parameters are grouped by the type of their values: numeric,
10 * empty, and custom.
11 *
12 * The enum values are arbitrary.  The literal transport parameter ID
13 * *values* (e.g. 0x1057 for loss bits) are not exposed by the API.
14 */
15enum transport_param_id
16{
17    /*
18     * Numeric transport parameters that have default values:
19     */
20    TPI_MAX_IDLE_TIMEOUT,
21    TPI_MAX_UDP_PAYLOAD_SIZE,
22    TPI_INIT_MAX_DATA,
23    TPI_INIT_MAX_STREAM_DATA_BIDI_LOCAL,
24    TPI_INIT_MAX_STREAM_DATA_BIDI_REMOTE,
25    TPI_INIT_MAX_STREAM_DATA_UNI,
26    TPI_INIT_MAX_STREAMS_BIDI,
27    TPI_INIT_MAX_STREAMS_UNI,
28    TPI_ACK_DELAY_EXPONENT,
29    TPI_MAX_ACK_DELAY,
30    TPI_ACTIVE_CONNECTION_ID_LIMIT,         MAX_NUM_WITH_DEF_TPI = TPI_ACTIVE_CONNECTION_ID_LIMIT,
31
32    /*
33     * Numeric transport parameters without default values:
34     */
35    TPI_MIN_ACK_DELAY,
36    /* The _02 version of MIN_ACK_DELAY is to support -02 version of the
37     * draft.  Functionally, it's exactly the same as -01, but without the
38     * extra enum there is no easy way to keep encoding and decoding simple.
39     * Because we support both, we don't care which one the peer selects.
40     * If the peer, like us, also sends both, we *assume* that the two
41     * versions of the transport parameter carry the same values.
42     */
43    TPI_MIN_ACK_DELAY_02,
44    TPI_TIMESTAMPS,
45    TPI_MAX_DATAGRAM_FRAME_SIZE,
46    TPI_LOSS_BITS,                          MAX_NUMERIC_TPI = TPI_LOSS_BITS,
47
48    /*
49     * Empty transport parameters:
50     */
51    TPI_GREASE_QUIC_BIT,
52    TPI_DISABLE_ACTIVE_MIGRATION,           MAX_EMPTY_TPI = TPI_DISABLE_ACTIVE_MIGRATION,
53
54    /*
55     * Custom handlers:
56     */
57    TPI_PREFERRED_ADDRESS,
58        /* CIDs must be in a contiguous range for tp_cids array to work */
59#define FIRST_TP_CID TPI_ORIGINAL_DEST_CID
60    TPI_ORIGINAL_DEST_CID,
61    TPI_INITIAL_SOURCE_CID,
62#define LAST_TP_CID TPI_RETRY_SOURCE_CID
63    TPI_RETRY_SOURCE_CID,
64#if LSQUIC_TEST_QUANTUM_READINESS
65    TPI_QUANTUM_READINESS,
66#endif
67    TPI_STATELESS_RESET_TOKEN,              LAST_TPI = TPI_STATELESS_RESET_TOKEN
68};
69
70#define TP_CID_IDX(tpi_) ((tpi_) - FIRST_TP_CID)
71
72
73struct transport_params
74{
75    /* Which transport parameters values are set: */
76    unsigned                tp_set;
77
78    /* Which transport parameters were present (set by the decoder): */
79    unsigned                tp_decoded;
80
81    uint64_t                tp_numerics[MAX_NUMERIC_TPI + 1];
82
83#define tp_init_max_stream_data_bidi_local  tp_numerics[TPI_INIT_MAX_STREAM_DATA_BIDI_LOCAL]
84#define tp_init_max_stream_data_bidi_remote tp_numerics[TPI_INIT_MAX_STREAM_DATA_BIDI_REMOTE]
85#define tp_init_max_stream_data_uni         tp_numerics[TPI_INIT_MAX_STREAM_DATA_UNI]
86#define tp_init_max_data                    tp_numerics[TPI_INIT_MAX_DATA]
87#define tp_max_idle_timeout                 tp_numerics[TPI_MAX_IDLE_TIMEOUT]
88#define tp_init_max_streams_bidi            tp_numerics[TPI_INIT_MAX_STREAMS_BIDI]
89#define tp_init_max_streams_uni             tp_numerics[TPI_INIT_MAX_STREAMS_UNI]
90#define tp_max_udp_payload_size             tp_numerics[TPI_MAX_UDP_PAYLOAD_SIZE]
91#define tp_ack_delay_exponent               tp_numerics[TPI_ACK_DELAY_EXPONENT]
92#define tp_max_ack_delay                    tp_numerics[TPI_MAX_ACK_DELAY]
93#define tp_active_connection_id_limit       tp_numerics[TPI_ACTIVE_CONNECTION_ID_LIMIT]
94#define tp_loss_bits                        tp_numerics[TPI_LOSS_BITS]
95
96    uint8_t     tp_stateless_reset_token[IQUIC_SRESET_TOKEN_SZ];
97    struct {
98        uint8_t         ipv4_addr[4];
99        uint16_t        ipv4_port;
100        uint8_t         ipv6_addr[16];
101        uint16_t        ipv6_port;
102        lsquic_cid_t    cid;
103        uint8_t         srst[IQUIC_SRESET_TOKEN_SZ];
104    }           tp_preferred_address;
105    lsquic_cid_t    tp_cids[3];
106#define tp_original_dest_cid tp_cids[TP_CID_IDX(TPI_ORIGINAL_DEST_CID)]
107#define tp_initial_source_cid tp_cids[TP_CID_IDX(TPI_INITIAL_SOURCE_CID)]
108#define tp_retry_source_cid tp_cids[TP_CID_IDX(TPI_RETRY_SOURCE_CID)]
109};
110
111#define MAX_TP_STR_SZ ((LAST_TPI + 1) *                                     \
112    (34 /* longest entry in tt2str */ + 2 /* semicolon */ + 2 /* colon */)  \
113  + INET_ADDRSTRLEN + INET6_ADDRSTRLEN + 5 /* Port */ * 2                   \
114  + MAX_CID_LEN * 2 * 4 /* there are four CIDs */                           \
115  + 11 * (MAX_NUMERIC_TPI + 1)                                              \
116  + IQUIC_SRESET_TOKEN_SZ * 2 * 2 /* there are two reset tokens */)
117
118#define TP_DEF_MAX_UDP_PAYLOAD_SIZE 65527
119#define TP_DEF_ACK_DELAY_EXP 3
120#define TP_DEF_INIT_MAX_STREAMS_UNI 0
121#define TP_DEF_INIT_MAX_STREAMS_BIDI 0
122#define TP_DEF_INIT_MAX_DATA 0
123#define TP_DEF_DISABLE_ACTIVE_MIGRATION 0
124#define TP_DEF_INIT_MAX_STREAM_DATA_BIDI_LOCAL 0
125#define TP_DEF_INIT_MAX_STREAM_DATA_BIDI_REMOTE 0
126#define TP_DEF_INIT_MAX_STREAM_DATA_UNI 0
127#define TP_DEF_MAX_IDLE_TIMEOUT 0
128#define TP_DEF_MAX_ACK_DELAY 25u
129#define TP_DEF_ACTIVE_CONNECTION_ID_LIMIT 2
130
131/* [draft-ietf-quic-transport-18], Section 18.1 */
132#define TP_MAX_MAX_ACK_DELAY ((1u << 14) - 1)
133
134#define TP_DEFAULT_VALUES                                                             \
135    .tp_set = ((1 << (MAX_NUM_WITH_DEF_TPI + 1)) - 1),                                \
136    .tp_active_connection_id_limit        =  TP_DEF_ACTIVE_CONNECTION_ID_LIMIT,       \
137    .tp_max_idle_timeout                  =  TP_DEF_MAX_IDLE_TIMEOUT,                 \
138    .tp_max_ack_delay                     =  TP_DEF_MAX_ACK_DELAY,                    \
139    .tp_max_udp_payload_size              =  TP_DEF_MAX_UDP_PAYLOAD_SIZE,             \
140    .tp_ack_delay_exponent                =  TP_DEF_ACK_DELAY_EXP,                    \
141    .tp_init_max_streams_bidi             =  TP_DEF_INIT_MAX_STREAMS_BIDI,            \
142    .tp_init_max_streams_uni              =  TP_DEF_INIT_MAX_STREAMS_UNI,             \
143    .tp_init_max_data                     =  TP_DEF_INIT_MAX_DATA,                    \
144    .tp_init_max_stream_data_bidi_local   =  TP_DEF_INIT_MAX_STREAM_DATA_BIDI_LOCAL,  \
145    .tp_init_max_stream_data_bidi_remote  =  TP_DEF_INIT_MAX_STREAM_DATA_BIDI_REMOTE, \
146    .tp_init_max_stream_data_uni          =  TP_DEF_INIT_MAX_STREAM_DATA_UNI
147
148#define TP_INITIALIZER() (struct transport_params) { TP_DEFAULT_VALUES }
149
150int
151lsquic_tp_encode (const struct transport_params *, int is_server,
152                  unsigned char *const buf, size_t bufsz);
153
154int
155lsquic_tp_decode (const unsigned char *const buf, size_t bufsz,
156    /* This argument specifies whose transport parameters we are parsing.  If
157     * true, we are parsing parameters sent by the server; if false, we are
158     * parsing parameteres sent by the client.
159     */
160                  int is_server,
161                  struct transport_params *);
162
163void
164lsquic_tp_to_str (const struct transport_params *params, char *buf, size_t sz);
165
166int
167lsquic_tp_encode_27 (const struct transport_params *, int is_server,
168                  unsigned char *const buf, size_t bufsz);
169
170int
171lsquic_tp_decode_27 (const unsigned char *const buf, size_t bufsz,
172                  int is_server,
173                  struct transport_params *);
174
175void
176lsquic_tp_to_str_27 (const struct transport_params *params, char *buf, size_t sz);
177
178int
179lsquic_tp_has_pref_ipv4 (const struct transport_params *);
180
181int
182lsquic_tp_has_pref_ipv6 (const struct transport_params *);
183
184extern const char * const lsquic_tpi2str[LAST_TPI + 1];
185
186/* From [draft-huitema-quic-ts-03] */
187#define TS_WANT_THEM            1
188#define TS_GENERATE_THEM        2
189
190#if LSQUIC_TEST_QUANTUM_READINESS
191size_t
192lsquic_tp_get_quantum_sz (void);
193#endif
194
195#define SERVER_0RTT_TPS                                              (0 \
196    /* [draft-ietf-quic-transport-31] Section 7.4.1: */                 \
197    | (1 << TPI_ACTIVE_CONNECTION_ID_LIMIT)                             \
198    | (1 << TPI_INIT_MAX_DATA)                                          \
199    | (1 << TPI_INIT_MAX_STREAMS_UNI)                                   \
200    | (1 << TPI_INIT_MAX_STREAMS_BIDI)                                  \
201    | (1 << TPI_INIT_MAX_STREAM_DATA_BIDI_LOCAL)                        \
202    | (1 << TPI_INIT_MAX_STREAM_DATA_BIDI_REMOTE)                       \
203    | (1 << TPI_INIT_MAX_STREAM_DATA_UNI)                               \
204    | (1 << TPI_MAX_IDLE_TIMEOUT)                                       \
205    | (1 << TPI_MAX_UDP_PAYLOAD_SIZE)                                   \
206    | (1 << TPI_DISABLE_ACTIVE_MIGRATION)                               \
207    /* Not including TPI_LOSS_BITS, see                              */ \
208    /* draft-ferrieuxhamchaoui-quic-lossbits-03, Section 5.1         */ \
209    /* [draft-ietf-quic-datagram-01] Section 3:                      */ \
210    | (1 << TPI_MAX_DATAGRAM_FRAME_SIZE)                                \
211    /* [draft-iyengar-quic-delayed-ack-01] does not specfiy, store:  */ \
212    | (1 << TPI_MIN_ACK_DELAY)                                          \
213    /* [draft-iyengar-quic-delayed-ack-02] does not specfiy, store:  */ \
214    | (1 << TPI_MIN_ACK_DELAY_02)                                       \
215    /* [draft-huitema-quic-ts-03] does not specfiy, store:           */ \
216    | (1 << TPI_TIMESTAMPS)                                             \
217)
218
219/* We always send the minimum ACK delay as 10ms; it is not configurable.
220 * There is nothing special about this particular value, except that it
221 * is not "too small" -- that is, it's within an order of magnitude from
222 * the maximum ACK delay of 25ms.  10ms seems like a safe lower bound for
223 * the ACK delay without performing more research.
224 */
225#define TP_MIN_ACK_DELAY 10000u
226
227#endif
228