include/internal/quic_txp.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_QUIC_TXP_H
  11 # define OSSL_QUIC_TXP_H
  12
  13 # include <openssl/ssl.h>
  14 # include "internal/quic_types.h"
  15 # include "internal/quic_record_tx.h"
  16 # include "internal/quic_cfq.h"
  17 # include "internal/quic_txpim.h"
  18 # include "internal/quic_stream.h"
  19 # include "internal/quic_stream_map.h"
  20 # include "internal/quic_fc.h"
  21 # include "internal/bio_addr.h"
  22 # include "internal/time.h"
  23
  24 # ifndef OPENSSL_NO_QUIC
  25
  26 /*
  27  * QUIC TX Packetiser
  28  * ==================
  29  */
  30 typedef struct ossl_quic_tx_packetiser_args_st {
  31     /* Configuration Settings */
  32     QUIC_CONN_ID    cur_scid;   /* Current Source Connection ID we use. */
  33     QUIC_CONN_ID    cur_dcid;   /* Current Destination Connection ID we use. */
  34     BIO_ADDR        peer;       /* Current destination L4 address we use. */
  35     uint32_t        ack_delay_exponent; /* ACK delay exponent used when encoding. */
  36
  37     /* Injected Dependencies */
  38     OSSL_QTX        *qtx;       /* QUIC Record Layer TX we are using */
  39     QUIC_TXPIM      *txpim;     /* QUIC TX'd Packet Information Manager */
  40     QUIC_CFQ        *cfq;       /* QUIC Control Frame Queue */
  41     OSSL_ACKM       *ackm;      /* QUIC Acknowledgement Manager */
  42     QUIC_STREAM_MAP *qsm;       /* QUIC Streams Map */
  43     QUIC_TXFC       *conn_txfc; /* QUIC Connection-Level TX Flow Controller */
  44     QUIC_RXFC       *conn_rxfc; /* QUIC Connection-Level RX Flow Controller */
  45     const OSSL_CC_METHOD *cc_method; /* QUIC Congestion Controller */
  46     OSSL_CC_DATA    *cc_data;   /* QUIC Congestion Controller Instance */
  47     OSSL_TIME       (*now)(void *arg);  /* Callback to get current time. */
  48     void            *now_arg;
  49
  50     /*
  51      * Injected dependencies - crypto streams.
  52      *
  53      * Note: There is no crypto stream for the 0-RTT EL.
  54      *       crypto[QUIC_PN_SPACE_APP] is the 1-RTT crypto stream.
  55      */
  56     QUIC_SSTREAM    *crypto[QUIC_PN_SPACE_NUM];
  57 } OSSL_QUIC_TX_PACKETISER_ARGS;
  58
  59 typedef struct ossl_quic_tx_packetiser_st OSSL_QUIC_TX_PACKETISER;
  60
  61 OSSL_QUIC_TX_PACKETISER *ossl_quic_tx_packetiser_new(const OSSL_QUIC_TX_PACKETISER_ARGS *args);
  62
  63 typedef void (ossl_quic_initial_token_free_fn)(const unsigned char *buf,
  64                                                size_t buf_len, void *arg);
  65
  66 void ossl_quic_tx_packetiser_free(OSSL_QUIC_TX_PACKETISER *txp);
  67
  68 /* Generate normal packets containing most frame types. */
  69 #define TX_PACKETISER_ARCHETYPE_NORMAL      0
  70 /* Generate ACKs only. */
  71 #define TX_PACKETISER_ARCHETYPE_ACK_ONLY    1
  72 #define TX_PACKETISER_ARCHETYPE_NUM         2
  73
  74 /*
  75  * Generates a datagram by polling the various ELs to determine if they want to
  76  * generate any frames, and generating a datagram which coalesces packets for
  77  * any ELs which do.
  78  *
  79  * archetype is a TX_PACKETISER_ARCHETYPE_* value.
  80  *
  81  * Returns TX_PACKETISER_RES_FAILURE on failure (e.g. allocation error),
  82  * TX_PACKETISER_RES_NO_PKT if no packets were sent (e.g. because nothing wants
  83  * to send anything), and TX_PACKETISER_RES_SENT_PKT if packets were sent.
  84  *
  85  * If an ACK-eliciting packet was sent, 1 is written to *sent_ack_eliciting,
  86  * otherwise *sent_ack_eliciting is unchanged.
  87  */
  88 #define TX_PACKETISER_RES_FAILURE   0
  89 #define TX_PACKETISER_RES_NO_PKT    1
  90 #define TX_PACKETISER_RES_SENT_PKT  2
  91 int ossl_quic_tx_packetiser_generate(OSSL_QUIC_TX_PACKETISER *txp,
  92                                      uint32_t archetype,
  93                                      int *sent_ack_eliciting);
  94
  95 /*
  96  * Returns 1 if one or more packets would be generated if
  97  * ossl_quic_tx_packetiser_generate were called.
  98  *
  99  * If TX_PACKETISER_BYPASS_CC is set in flags, congestion control is
 100  * ignored for the purposes of making this determination.
 101  */
 102 #define TX_PACKETISER_BYPASS_CC   (1U << 0)
 103
 104 int ossl_quic_tx_packetiser_has_pending(OSSL_QUIC_TX_PACKETISER *txp,
 105                                         uint32_t archetype,
 106                                         uint32_t flags);
 107
 108 /*
 109  * Set the token used in Initial packets. The callback is called when the buffer
 110  * is no longer needed; for example, when the TXP is freed or when this function
 111  * is called again with a new buffer.
 112  */
 113 void ossl_quic_tx_packetiser_set_initial_token(OSSL_QUIC_TX_PACKETISER *txp,
 114                                                const unsigned char *token,
 115                                                size_t token_len,
 116                                                ossl_quic_initial_token_free_fn *free_cb,
 117                                                void *free_cb_arg);
 118
 119 /* Change the DCID the TXP uses to send outgoing packets. */
 120 int ossl_quic_tx_packetiser_set_cur_dcid(OSSL_QUIC_TX_PACKETISER *txp,
 121                                          const QUIC_CONN_ID *dcid);
 122
 123 /* Change the SCID the TXP uses to send outgoing (long) packets. */
 124 int ossl_quic_tx_packetiser_set_cur_scid(OSSL_QUIC_TX_PACKETISER *txp,
 125                                          const QUIC_CONN_ID *scid);
 126
 127 /* Change the destination L4 address the TXP uses to send datagrams. */
 128 int ossl_quic_tx_packetiser_set_peer(OSSL_QUIC_TX_PACKETISER *txp,
 129                                      const BIO_ADDR *peer);
 130
 131 /*
 132  * Inform the TX packetiser that an EL has been discarded. Idempotent.
 133  *
 134  * This does not inform the QTX as well; the caller must also inform the QTX.
 135  *
 136  * The TXP will no longer reference the crypto[enc_level] QUIC_SSTREAM which was
 137  * provided in the TXP arguments. However, it is the callers responsibility to
 138  * free that QUIC_SSTREAM if desired.
 139  */
 140 int ossl_quic_tx_packetiser_discard_enc_level(OSSL_QUIC_TX_PACKETISER *txp,
 141                                               uint32_t enc_level);
 142
 143 /*
 144  * Informs the TX packetiser that the handshake is complete. The TX packetiser
 145  * will not send 1-RTT application data until the handshake is complete,
 146  * as the authenticity of the peer is not confirmed until the handshake
 147  * complete event occurs.
 148  */
 149 void ossl_quic_tx_packetiser_notify_handshake_complete(OSSL_QUIC_TX_PACKETISER *txp);
 150
 151 /* Asks the TXP to generate a HANDSHAKE_DONE frame in the next 1-RTT packet. */
 152 void ossl_quic_tx_packetiser_schedule_handshake_done(OSSL_QUIC_TX_PACKETISER *txp);
 153
 154 /* Asks the TXP to ensure the next packet in the given PN space is ACK-eliciting. */
 155 void ossl_quic_tx_packetiser_schedule_ack_eliciting(OSSL_QUIC_TX_PACKETISER *txp,
 156                                                     uint32_t pn_space);
 157
 158 /*
 159  * Schedules a connection close. *f and f->reason are copied. This operation is
 160  * irreversible and causes all further packets generated by the TXP to contain a
 161  * CONNECTION_CLOSE frame. This function fails if it has already been called
 162  * successfully; the information in *f cannot be changed after the first
 163  * successful call to this function.
 164  */
 165 int ossl_quic_tx_packetiser_schedule_conn_close(OSSL_QUIC_TX_PACKETISER *txp,
 166                                                 const OSSL_QUIC_FRAME_CONN_CLOSE *f);
 167
 168 # endif
 169
 170 #endif