2 * Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
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
10 #ifndef OSSL_QUIC_TXP_H
11 # define OSSL_QUIC_TXP_H
13 # include <openssl/ssl.h>
14 # include "internal/quic_types.h"
15 # include "internal/quic_predef.h"
16 # include "internal/quic_record_tx.h"
17 # include "internal/quic_cfq.h"
18 # include "internal/quic_txpim.h"
19 # include "internal/quic_stream.h"
20 # include "internal/quic_stream_map.h"
21 # include "internal/quic_fc.h"
22 # include "internal/bio_addr.h"
23 # include "internal/time.h"
24 # include "internal/qlog.h"
26 # ifndef OPENSSL_NO_QUIC
32 typedef struct ossl_quic_tx_packetiser_args_st {
33 /* Configuration Settings */
34 QUIC_CONN_ID cur_scid; /* Current Source Connection ID we use. */
35 QUIC_CONN_ID cur_dcid; /* Current Destination Connection ID we use. */
36 BIO_ADDR peer; /* Current destination L4 address we use. */
37 uint32_t ack_delay_exponent; /* ACK delay exponent used when encoding. */
39 /* Injected Dependencies */
40 OSSL_QTX *qtx; /* QUIC Record Layer TX we are using */
41 QUIC_TXPIM *txpim; /* QUIC TX'd Packet Information Manager */
42 QUIC_CFQ *cfq; /* QUIC Control Frame Queue */
43 OSSL_ACKM *ackm; /* QUIC Acknowledgement Manager */
44 QUIC_STREAM_MAP *qsm; /* QUIC Streams Map */
45 QUIC_TXFC *conn_txfc; /* QUIC Connection-Level TX Flow Controller */
46 QUIC_RXFC *conn_rxfc; /* QUIC Connection-Level RX Flow Controller */
47 QUIC_RXFC *max_streams_bidi_rxfc; /* QUIC RXFC for MAX_STREAMS generation */
48 QUIC_RXFC *max_streams_uni_rxfc;
49 const OSSL_CC_METHOD *cc_method; /* QUIC Congestion Controller */
50 OSSL_CC_DATA *cc_data; /* QUIC Congestion Controller Instance */
51 OSSL_TIME (*now)(void *arg); /* Callback to get current time. */
53 QLOG *qlog; /* Optional QLOG instance */
56 * Injected dependencies - crypto streams.
58 * Note: There is no crypto stream for the 0-RTT EL.
59 * crypto[QUIC_PN_SPACE_APP] is the 1-RTT crypto stream.
61 QUIC_SSTREAM *crypto[QUIC_PN_SPACE_NUM];
63 } OSSL_QUIC_TX_PACKETISER_ARGS;
65 OSSL_QUIC_TX_PACKETISER *ossl_quic_tx_packetiser_new(const OSSL_QUIC_TX_PACKETISER_ARGS *args);
67 typedef void (ossl_quic_initial_token_free_fn)(const unsigned char *buf,
68 size_t buf_len, void *arg);
70 void ossl_quic_tx_packetiser_free(OSSL_QUIC_TX_PACKETISER *txp);
73 * When in the closing state we need to maintain a count of received bytes
74 * so that we can limit the number of close connection frames we send.
75 * Refer RFC 9000 s. 10.2.1 Closing Connection State.
77 void ossl_quic_tx_packetiser_record_received_closing_bytes(
78 OSSL_QUIC_TX_PACKETISER *txp, size_t n);
81 * Generates a datagram by polling the various ELs to determine if they want to
82 * generate any frames, and generating a datagram which coalesces packets for
85 * Returns 0 on failure (e.g. allocation error or other errors), 1 otherwise.
87 * *status is filled with status information about the generated packet.
88 * It is always filled even in case of failure. In particular, packets can be
89 * sent even if failure is later returned.
90 * See QUIC_TXP_STATUS for details.
92 typedef struct quic_txp_status_st {
93 int sent_ack_eliciting; /* Was an ACK-eliciting packet sent? */
94 int sent_handshake; /* Was a Handshake packet sent? */
95 size_t sent_pkt; /* Number of packets sent (0 if nothing was sent) */
98 int ossl_quic_tx_packetiser_generate(OSSL_QUIC_TX_PACKETISER *txp,
99 QUIC_TXP_STATUS *status);
102 * Returns a deadline after which a call to ossl_quic_tx_packetiser_generate()
103 * might succeed even if it did not previously. This may return
104 * ossl_time_infinite() if there is no such deadline currently applicable. It
105 * returns ossl_time_zero() if there is (potentially) more data to be generated
106 * immediately. The value returned is liable to change after any call to
107 * ossl_quic_tx_packetiser_generate() (or after ACKM or CC state changes). Note
108 * that ossl_quic_tx_packetiser_generate() can also start to succeed for other
109 * non-chronological reasons, such as changes to send stream buffers, etc.
111 OSSL_TIME ossl_quic_tx_packetiser_get_deadline(OSSL_QUIC_TX_PACKETISER *txp);
114 * Set the token used in Initial packets. The callback is called when the buffer
115 * is no longer needed; for example, when the TXP is freed or when this function
116 * is called again with a new buffer. Fails returning 0 if the token is too big
117 * to ever be reasonably encapsulated in an outgoing packet based on our current
118 * understanding of our PMTU.
120 int ossl_quic_tx_packetiser_set_initial_token(OSSL_QUIC_TX_PACKETISER *txp,
121 const unsigned char *token,
123 ossl_quic_initial_token_free_fn *free_cb,
126 /* Change the DCID the TXP uses to send outgoing packets. */
127 int ossl_quic_tx_packetiser_set_cur_dcid(OSSL_QUIC_TX_PACKETISER *txp,
128 const QUIC_CONN_ID *dcid);
130 /* Change the SCID the TXP uses to send outgoing (long) packets. */
131 int ossl_quic_tx_packetiser_set_cur_scid(OSSL_QUIC_TX_PACKETISER *txp,
132 const QUIC_CONN_ID *scid);
135 * Change the destination L4 address the TXP uses to send datagrams. Specify
136 * NULL (or AF_UNSPEC) to disable use of addressed mode.
138 int ossl_quic_tx_packetiser_set_peer(OSSL_QUIC_TX_PACKETISER *txp,
139 const BIO_ADDR *peer);
142 * Change the QLOG instance in use after instantiation.
144 void ossl_quic_tx_packetiser_set0_qlog(OSSL_QUIC_TX_PACKETISER *txp,
148 * Inform the TX packetiser that an EL has been discarded. Idempotent.
150 * This does not inform the QTX as well; the caller must also inform the QTX.
152 * The TXP will no longer reference the crypto[enc_level] QUIC_SSTREAM which was
153 * provided in the TXP arguments. However, it is the callers responsibility to
154 * free that QUIC_SSTREAM if desired.
156 int ossl_quic_tx_packetiser_discard_enc_level(OSSL_QUIC_TX_PACKETISER *txp,
160 * Informs the TX packetiser that the handshake is complete. The TX packetiser
161 * will not send 1-RTT application data until the handshake is complete,
162 * as the authenticity of the peer is not confirmed until the handshake
163 * complete event occurs.
165 void ossl_quic_tx_packetiser_notify_handshake_complete(OSSL_QUIC_TX_PACKETISER *txp);
167 /* Asks the TXP to generate a HANDSHAKE_DONE frame in the next 1-RTT packet. */
168 void ossl_quic_tx_packetiser_schedule_handshake_done(OSSL_QUIC_TX_PACKETISER *txp);
170 /* Asks the TXP to ensure the next packet in the given PN space is ACK-eliciting. */
171 void ossl_quic_tx_packetiser_schedule_ack_eliciting(OSSL_QUIC_TX_PACKETISER *txp,
175 * Asks the TXP to ensure an ACK is put in the next packet in the given PN
178 void ossl_quic_tx_packetiser_schedule_ack(OSSL_QUIC_TX_PACKETISER *txp,
182 * Schedules a connection close. *f and f->reason are copied. This operation is
183 * irreversible and causes all further packets generated by the TXP to contain a
184 * CONNECTION_CLOSE frame. This function fails if it has already been called
185 * successfully; the information in *f cannot be changed after the first
186 * successful call to this function.
188 int ossl_quic_tx_packetiser_schedule_conn_close(OSSL_QUIC_TX_PACKETISER *txp,
189 const OSSL_QUIC_FRAME_CONN_CLOSE *f);
191 /* Setters for the msg_callback and msg_callback_arg */
192 void ossl_quic_tx_packetiser_set_msg_callback(OSSL_QUIC_TX_PACKETISER *txp,
193 ossl_msg_cb msg_callback,
194 SSL *msg_callback_ssl);
195 void ossl_quic_tx_packetiser_set_msg_callback_arg(OSSL_QUIC_TX_PACKETISER *txp,
196 void *msg_callback_arg);
199 * Determines the next PN which will be used for a given PN space.
201 QUIC_PN ossl_quic_tx_packetiser_get_next_pn(OSSL_QUIC_TX_PACKETISER *txp,
205 * Sets a callback which is called whenever TXP sends an ACK frame. The callee
206 * must not modify the ACK frame data. Can be used to snoop on PNs being ACKed.
208 void ossl_quic_tx_packetiser_set_ack_tx_cb(OSSL_QUIC_TX_PACKETISER *txp,
209 void (*cb)(const OSSL_QUIC_FRAME_ACK *ack,