1*e7be843bSPierre Pronchery /* 2*e7be843bSPierre Pronchery * Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved. 3*e7be843bSPierre Pronchery * 4*e7be843bSPierre Pronchery * Licensed under the Apache License 2.0 (the "License"). You may not use 5*e7be843bSPierre Pronchery * this file except in compliance with the License. You can obtain a copy 6*e7be843bSPierre Pronchery * in the file LICENSE in the source distribution or at 7*e7be843bSPierre Pronchery * https://www.openssl.org/source/license.html 8*e7be843bSPierre Pronchery */ 9*e7be843bSPierre Pronchery 10*e7be843bSPierre Pronchery #ifndef OSSL_QUIC_FC_H 11*e7be843bSPierre Pronchery # define OSSL_QUIC_FC_H 12*e7be843bSPierre Pronchery 13*e7be843bSPierre Pronchery # include <openssl/ssl.h> 14*e7be843bSPierre Pronchery # include "internal/time.h" 15*e7be843bSPierre Pronchery 16*e7be843bSPierre Pronchery # ifndef OPENSSL_NO_QUIC 17*e7be843bSPierre Pronchery 18*e7be843bSPierre Pronchery /* 19*e7be843bSPierre Pronchery * TX Flow Controller (TXFC) 20*e7be843bSPierre Pronchery * ========================= 21*e7be843bSPierre Pronchery * 22*e7be843bSPierre Pronchery * For discussion, see doc/designs/quic-design/quic-fc.md. 23*e7be843bSPierre Pronchery */ 24*e7be843bSPierre Pronchery typedef struct quic_txfc_st QUIC_TXFC; 25*e7be843bSPierre Pronchery 26*e7be843bSPierre Pronchery struct quic_txfc_st { 27*e7be843bSPierre Pronchery QUIC_TXFC *parent; /* stream-level iff non-NULL */ 28*e7be843bSPierre Pronchery uint64_t swm, cwm; 29*e7be843bSPierre Pronchery char has_become_blocked; 30*e7be843bSPierre Pronchery }; 31*e7be843bSPierre Pronchery 32*e7be843bSPierre Pronchery /* 33*e7be843bSPierre Pronchery * Initialises a TX flow controller. conn_txfc should be non-NULL and point to 34*e7be843bSPierre Pronchery * the connection-level flow controller if the TXFC is for stream-level flow 35*e7be843bSPierre Pronchery * control, and NULL otherwise. 36*e7be843bSPierre Pronchery */ 37*e7be843bSPierre Pronchery int ossl_quic_txfc_init(QUIC_TXFC *txfc, QUIC_TXFC *conn_txfc); 38*e7be843bSPierre Pronchery 39*e7be843bSPierre Pronchery /* 40*e7be843bSPierre Pronchery * Gets the parent (i.e., connection-level) TX flow controller. Returns NULL if 41*e7be843bSPierre Pronchery * called on a connection-level TX flow controller. 42*e7be843bSPierre Pronchery */ 43*e7be843bSPierre Pronchery QUIC_TXFC *ossl_quic_txfc_get_parent(QUIC_TXFC *txfc); 44*e7be843bSPierre Pronchery 45*e7be843bSPierre Pronchery /* 46*e7be843bSPierre Pronchery * Bump the credit watermark (CWM) value. This is the 'On TX Window Updated' 47*e7be843bSPierre Pronchery * operation. This function is a no-op if it has already been called with an 48*e7be843bSPierre Pronchery * equal or higher CWM value. 49*e7be843bSPierre Pronchery * 50*e7be843bSPierre Pronchery * It returns 1 iff the call resulted in the CWM being bumped and 0 if it was 51*e7be843bSPierre Pronchery * not increased because it has already been called with an equal or higher CWM 52*e7be843bSPierre Pronchery * value. This is not an error per se but may indicate a local programming error 53*e7be843bSPierre Pronchery * or a protocol error in a remote peer. 54*e7be843bSPierre Pronchery */ 55*e7be843bSPierre Pronchery int ossl_quic_txfc_bump_cwm(QUIC_TXFC *txfc, uint64_t cwm); 56*e7be843bSPierre Pronchery 57*e7be843bSPierre Pronchery /* 58*e7be843bSPierre Pronchery * Get the number of bytes by which we are in credit. This is the number of 59*e7be843bSPierre Pronchery * controlled bytes we are allowed to send. (Thus if this function returns 0, we 60*e7be843bSPierre Pronchery * are currently blocked.) 61*e7be843bSPierre Pronchery * 62*e7be843bSPierre Pronchery * If called on a stream-level TXFC, ossl_quic_txfc_get_credit is called on 63*e7be843bSPierre Pronchery * the connection-level TXFC as well, and the lesser of the two values is 64*e7be843bSPierre Pronchery * returned. The consumed value is the amount already consumed on the connection 65*e7be843bSPierre Pronchery * level TXFC. 66*e7be843bSPierre Pronchery */ 67*e7be843bSPierre Pronchery uint64_t ossl_quic_txfc_get_credit(QUIC_TXFC *txfc, uint64_t consumed); 68*e7be843bSPierre Pronchery 69*e7be843bSPierre Pronchery /* 70*e7be843bSPierre Pronchery * Like ossl_quic_txfc_get_credit(), but when called on a stream-level TXFC, 71*e7be843bSPierre Pronchery * retrieves only the stream-level credit value and does not clamp it based on 72*e7be843bSPierre Pronchery * connection-level flow control. Any credit value is reduced by the consumed 73*e7be843bSPierre Pronchery * amount. 74*e7be843bSPierre Pronchery */ 75*e7be843bSPierre Pronchery uint64_t ossl_quic_txfc_get_credit_local(QUIC_TXFC *txfc, uint64_t consumed); 76*e7be843bSPierre Pronchery 77*e7be843bSPierre Pronchery /* 78*e7be843bSPierre Pronchery * Consume num_bytes of credit. This is the 'On TX' operation. This should be 79*e7be843bSPierre Pronchery * called when we transmit any controlled bytes. Calling this with an argument 80*e7be843bSPierre Pronchery * of 0 is a no-op. 81*e7be843bSPierre Pronchery * 82*e7be843bSPierre Pronchery * We must never transmit more controlled bytes than we are in credit for (see 83*e7be843bSPierre Pronchery * the return value of ossl_quic_txfc_get_credit()). If you call this function 84*e7be843bSPierre Pronchery * with num_bytes greater than our current credit, this function consumes the 85*e7be843bSPierre Pronchery * remainder of the credit and returns 0. This indicates a serious programming 86*e7be843bSPierre Pronchery * error on the caller's part. Otherwise, the function returns 1. 87*e7be843bSPierre Pronchery * 88*e7be843bSPierre Pronchery * If called on a stream-level TXFC, ossl_quic_txfc_consume_credit() is called 89*e7be843bSPierre Pronchery * on the connection-level TXFC also. If the call to that function on the 90*e7be843bSPierre Pronchery * connection-level TXFC returns zero, this function will also return zero. 91*e7be843bSPierre Pronchery */ 92*e7be843bSPierre Pronchery int ossl_quic_txfc_consume_credit(QUIC_TXFC *txfc, uint64_t num_bytes); 93*e7be843bSPierre Pronchery 94*e7be843bSPierre Pronchery /* 95*e7be843bSPierre Pronchery * Like ossl_quic_txfc_consume_credit(), but when called on a stream-level TXFC, 96*e7be843bSPierre Pronchery * consumes only from the stream-level credit and does not inform the 97*e7be843bSPierre Pronchery * connection-level TXFC. 98*e7be843bSPierre Pronchery */ 99*e7be843bSPierre Pronchery int ossl_quic_txfc_consume_credit_local(QUIC_TXFC *txfc, uint64_t num_bytes); 100*e7be843bSPierre Pronchery 101*e7be843bSPierre Pronchery /* 102*e7be843bSPierre Pronchery * This flag is provided for convenience. A caller is not required to use it. It 103*e7be843bSPierre Pronchery * is a boolean flag set whenever our credit drops to zero. If clear is 1, the 104*e7be843bSPierre Pronchery * flag is cleared. The old value of the flag is returned. Callers may use this 105*e7be843bSPierre Pronchery * to determine if they need to send a DATA_BLOCKED or STREAM_DATA_BLOCKED 106*e7be843bSPierre Pronchery * frame, which should contain the value returned by ossl_quic_txfc_get_cwm(). 107*e7be843bSPierre Pronchery */ 108*e7be843bSPierre Pronchery int ossl_quic_txfc_has_become_blocked(QUIC_TXFC *txfc, int clear); 109*e7be843bSPierre Pronchery 110*e7be843bSPierre Pronchery /* 111*e7be843bSPierre Pronchery * Get the current CWM value. This is mainly only needed when generating a 112*e7be843bSPierre Pronchery * DATA_BLOCKED or STREAM_DATA_BLOCKED frame, or for diagnostic purposes. 113*e7be843bSPierre Pronchery */ 114*e7be843bSPierre Pronchery uint64_t ossl_quic_txfc_get_cwm(QUIC_TXFC *txfc); 115*e7be843bSPierre Pronchery 116*e7be843bSPierre Pronchery /* 117*e7be843bSPierre Pronchery * Get the current spent watermark (SWM) value. This is purely for diagnostic 118*e7be843bSPierre Pronchery * use and should not be needed in normal circumstances. 119*e7be843bSPierre Pronchery */ 120*e7be843bSPierre Pronchery uint64_t ossl_quic_txfc_get_swm(QUIC_TXFC *txfc); 121*e7be843bSPierre Pronchery 122*e7be843bSPierre Pronchery /* 123*e7be843bSPierre Pronchery * RX Flow Controller (RXFC) 124*e7be843bSPierre Pronchery * ========================= 125*e7be843bSPierre Pronchery */ 126*e7be843bSPierre Pronchery typedef struct quic_rxfc_st QUIC_RXFC; 127*e7be843bSPierre Pronchery 128*e7be843bSPierre Pronchery struct quic_rxfc_st { 129*e7be843bSPierre Pronchery /* 130*e7be843bSPierre Pronchery * swm is the sent/received watermark, which tracks how much we have 131*e7be843bSPierre Pronchery * received from the peer. rwm is the retired watermark, which tracks how 132*e7be843bSPierre Pronchery * much has been passed to the application. esrwm is the rwm value at which 133*e7be843bSPierre Pronchery * the current auto-tuning epoch started. hwm is the highest stream length 134*e7be843bSPierre Pronchery * (STREAM frame offset + payload length) we have seen from a STREAM frame 135*e7be843bSPierre Pronchery * yet. 136*e7be843bSPierre Pronchery */ 137*e7be843bSPierre Pronchery uint64_t cwm, swm, rwm, esrwm, hwm, cur_window_size, max_window_size; 138*e7be843bSPierre Pronchery OSSL_TIME epoch_start; 139*e7be843bSPierre Pronchery OSSL_TIME (*now)(void *arg); 140*e7be843bSPierre Pronchery void *now_arg; 141*e7be843bSPierre Pronchery QUIC_RXFC *parent; 142*e7be843bSPierre Pronchery unsigned char error_code, has_cwm_changed, is_fin, standalone; 143*e7be843bSPierre Pronchery }; 144*e7be843bSPierre Pronchery 145*e7be843bSPierre Pronchery /* 146*e7be843bSPierre Pronchery * Initialises an RX flow controller. conn_rxfc should be non-NULL and point to 147*e7be843bSPierre Pronchery * a connection-level RXFC if the RXFC is for stream-level flow control, and 148*e7be843bSPierre Pronchery * NULL otherwise. initial_window_size and max_window_size specify the initial 149*e7be843bSPierre Pronchery * and absolute maximum window sizes, respectively. Window size values are 150*e7be843bSPierre Pronchery * expressed in bytes and determine how much credit the RXFC extends to the peer 151*e7be843bSPierre Pronchery * to transmit more data at a time. 152*e7be843bSPierre Pronchery */ 153*e7be843bSPierre Pronchery int ossl_quic_rxfc_init(QUIC_RXFC *rxfc, QUIC_RXFC *conn_rxfc, 154*e7be843bSPierre Pronchery uint64_t initial_window_size, 155*e7be843bSPierre Pronchery uint64_t max_window_size, 156*e7be843bSPierre Pronchery OSSL_TIME (*now)(void *arg), 157*e7be843bSPierre Pronchery void *now_arg); 158*e7be843bSPierre Pronchery 159*e7be843bSPierre Pronchery /* 160*e7be843bSPierre Pronchery * Initialises an RX flow controller which is used by itself and not under a 161*e7be843bSPierre Pronchery * connection-level RX flow controller. This can be used for stream count 162*e7be843bSPierre Pronchery * enforcement as well as CRYPTO buffer enforcement. 163*e7be843bSPierre Pronchery */ 164*e7be843bSPierre Pronchery int ossl_quic_rxfc_init_standalone(QUIC_RXFC *rxfc, 165*e7be843bSPierre Pronchery uint64_t initial_window_size, 166*e7be843bSPierre Pronchery OSSL_TIME (*now)(void *arg), 167*e7be843bSPierre Pronchery void *now_arg); 168*e7be843bSPierre Pronchery 169*e7be843bSPierre Pronchery /* 170*e7be843bSPierre Pronchery * Gets the parent (i.e., connection-level) RXFC. Returns NULL if called on a 171*e7be843bSPierre Pronchery * connection-level RXFC. 172*e7be843bSPierre Pronchery */ 173*e7be843bSPierre Pronchery QUIC_RXFC *ossl_quic_rxfc_get_parent(QUIC_RXFC *rxfc); 174*e7be843bSPierre Pronchery 175*e7be843bSPierre Pronchery /* 176*e7be843bSPierre Pronchery * Changes the current maximum window size value. 177*e7be843bSPierre Pronchery */ 178*e7be843bSPierre Pronchery void ossl_quic_rxfc_set_max_window_size(QUIC_RXFC *rxfc, 179*e7be843bSPierre Pronchery size_t max_window_size); 180*e7be843bSPierre Pronchery 181*e7be843bSPierre Pronchery /* 182*e7be843bSPierre Pronchery * To be called whenever a STREAM frame is received. 183*e7be843bSPierre Pronchery * 184*e7be843bSPierre Pronchery * end is the value (offset + len), where offset is the offset field of the 185*e7be843bSPierre Pronchery * STREAM frame and len is the length of the STREAM frame's payload in bytes. 186*e7be843bSPierre Pronchery * 187*e7be843bSPierre Pronchery * is_fin should be 1 if the STREAM frame had the FIN flag set and 0 otherwise. 188*e7be843bSPierre Pronchery * 189*e7be843bSPierre Pronchery * This function may be used on a stream-level RXFC only. The connection-level 190*e7be843bSPierre Pronchery * RXFC will have its state updated by the stream-level RXFC. 191*e7be843bSPierre Pronchery * 192*e7be843bSPierre Pronchery * You should check ossl_quic_rxfc_has_error() on both connection-level and 193*e7be843bSPierre Pronchery * stream-level RXFCs after calling this function, as an incoming STREAM frame 194*e7be843bSPierre Pronchery * may cause flow control limits to be exceeded by an errant peer. This 195*e7be843bSPierre Pronchery * function still returns 1 in this case, as this is not a caller error. 196*e7be843bSPierre Pronchery * 197*e7be843bSPierre Pronchery * Returns 1 on success or 0 on failure. 198*e7be843bSPierre Pronchery */ 199*e7be843bSPierre Pronchery int ossl_quic_rxfc_on_rx_stream_frame(QUIC_RXFC *rxfc, 200*e7be843bSPierre Pronchery uint64_t end, int is_fin); 201*e7be843bSPierre Pronchery 202*e7be843bSPierre Pronchery /* 203*e7be843bSPierre Pronchery * To be called whenever controlled bytes are retired, i.e. when bytes are 204*e7be843bSPierre Pronchery * dequeued from a QUIC stream and passed to the application. num_bytes 205*e7be843bSPierre Pronchery * is the number of bytes which were passed to the application. 206*e7be843bSPierre Pronchery * 207*e7be843bSPierre Pronchery * You should call this only on a stream-level RXFC. This function will update 208*e7be843bSPierre Pronchery * the connection-level RXFC automatically. 209*e7be843bSPierre Pronchery * 210*e7be843bSPierre Pronchery * rtt should be the current best understanding of the RTT to the peer, as 211*e7be843bSPierre Pronchery * offered by the Statistics Manager. 212*e7be843bSPierre Pronchery * 213*e7be843bSPierre Pronchery * You should check ossl_quic_rxfc_has_cwm_changed() after calling this 214*e7be843bSPierre Pronchery * function, as it may have caused the RXFC to decide to grant more flow control 215*e7be843bSPierre Pronchery * credit to the peer. 216*e7be843bSPierre Pronchery * 217*e7be843bSPierre Pronchery * Returns 1 on success and 0 on failure. 218*e7be843bSPierre Pronchery */ 219*e7be843bSPierre Pronchery int ossl_quic_rxfc_on_retire(QUIC_RXFC *rxfc, 220*e7be843bSPierre Pronchery uint64_t num_bytes, 221*e7be843bSPierre Pronchery OSSL_TIME rtt); 222*e7be843bSPierre Pronchery 223*e7be843bSPierre Pronchery /* 224*e7be843bSPierre Pronchery * Returns the current CWM which the RXFC thinks the peer should have. 225*e7be843bSPierre Pronchery * 226*e7be843bSPierre Pronchery * Note that the RXFC will increase this value in response to events, at which 227*e7be843bSPierre Pronchery * time a MAX_DATA or MAX_STREAM_DATA frame must be generated. Use 228*e7be843bSPierre Pronchery * ossl_quic_rxfc_has_cwm_changed() to detect this condition. 229*e7be843bSPierre Pronchery * 230*e7be843bSPierre Pronchery * This value increases monotonically. 231*e7be843bSPierre Pronchery */ 232*e7be843bSPierre Pronchery uint64_t ossl_quic_rxfc_get_cwm(const QUIC_RXFC *rxfc); 233*e7be843bSPierre Pronchery 234*e7be843bSPierre Pronchery /* 235*e7be843bSPierre Pronchery * Returns the current SWM. This is the total number of bytes the peer has 236*e7be843bSPierre Pronchery * transmitted to us. This is intended for diagnostic use only; you should 237*e7be843bSPierre Pronchery * not need it. 238*e7be843bSPierre Pronchery */ 239*e7be843bSPierre Pronchery uint64_t ossl_quic_rxfc_get_swm(const QUIC_RXFC *rxfc); 240*e7be843bSPierre Pronchery 241*e7be843bSPierre Pronchery /* 242*e7be843bSPierre Pronchery * Returns the current RWM. This is the total number of bytes that has been 243*e7be843bSPierre Pronchery * retired. This is intended for diagnostic use only; you should not need it. 244*e7be843bSPierre Pronchery */ 245*e7be843bSPierre Pronchery uint64_t ossl_quic_rxfc_get_rwm(const QUIC_RXFC *rxfc); 246*e7be843bSPierre Pronchery 247*e7be843bSPierre Pronchery /* 248*e7be843bSPierre Pronchery * Returns the current credit. This is the CWM minus the SWM. This is intended 249*e7be843bSPierre Pronchery * for diagnostic use only; you should not need it. 250*e7be843bSPierre Pronchery */ 251*e7be843bSPierre Pronchery uint64_t ossl_quic_rxfc_get_credit(const QUIC_RXFC *rxfc); 252*e7be843bSPierre Pronchery 253*e7be843bSPierre Pronchery /* 254*e7be843bSPierre Pronchery * Returns the CWM changed flag. If clear is 1, the flag is cleared and the old 255*e7be843bSPierre Pronchery * value is returned. 256*e7be843bSPierre Pronchery */ 257*e7be843bSPierre Pronchery int ossl_quic_rxfc_has_cwm_changed(QUIC_RXFC *rxfc, int clear); 258*e7be843bSPierre Pronchery 259*e7be843bSPierre Pronchery /* 260*e7be843bSPierre Pronchery * Returns a QUIC_ERR_* error code if a flow control error has been detected. 261*e7be843bSPierre Pronchery * Otherwise, returns QUIC_ERR_NO_ERROR. If clear is 1, the error is cleared 262*e7be843bSPierre Pronchery * and the old value is returned. 263*e7be843bSPierre Pronchery * 264*e7be843bSPierre Pronchery * May return one of the following values: 265*e7be843bSPierre Pronchery * 266*e7be843bSPierre Pronchery * QUIC_ERR_FLOW_CONTROL_ERROR: 267*e7be843bSPierre Pronchery * This indicates a flow control protocol violation by the remote peer; the 268*e7be843bSPierre Pronchery * connection should be terminated in this event. 269*e7be843bSPierre Pronchery * QUIC_ERR_FINAL_SIZE: 270*e7be843bSPierre Pronchery * The peer attempted to change the stream length after ending the stream. 271*e7be843bSPierre Pronchery */ 272*e7be843bSPierre Pronchery int ossl_quic_rxfc_get_error(QUIC_RXFC *rxfc, int clear); 273*e7be843bSPierre Pronchery 274*e7be843bSPierre Pronchery /* 275*e7be843bSPierre Pronchery * Returns 1 if the RXFC is a stream-level RXFC and the RXFC knows the final 276*e7be843bSPierre Pronchery * size for the stream in bytes. If this is the case and final_size is non-NULL, 277*e7be843bSPierre Pronchery * writes the final size to *final_size. Otherwise, returns 0. 278*e7be843bSPierre Pronchery */ 279*e7be843bSPierre Pronchery int ossl_quic_rxfc_get_final_size(const QUIC_RXFC *rxfc, uint64_t *final_size); 280*e7be843bSPierre Pronchery 281*e7be843bSPierre Pronchery # endif 282*e7be843bSPierre Pronchery 283*e7be843bSPierre Pronchery #endif 284