diff options
author | Hugo Landau <hlandau@openssl.org> | 2022-08-22 17:32:16 +0300 |
---|---|---|
committer | Hugo Landau <hlandau@openssl.org> | 2022-09-26 10:01:55 +0300 |
commit | 508e087c4c9e0f6548816e0044022b257f179585 (patch) | |
tree | c0e0bd453c13213c4793330d6a4080b159619733 /include/internal | |
parent | 28a5aa0cbdddfdf4d82a437d72407d4f52d4e54a (diff) |
QUIC Flow Control
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19040)
Diffstat (limited to 'include/internal')
-rw-r--r-- | include/internal/quic_error.h | 38 | ||||
-rw-r--r-- | include/internal/quic_fc.h | 256 |
2 files changed, 294 insertions, 0 deletions
diff --git a/include/internal/quic_error.h b/include/internal/quic_error.h new file mode 100644 index 0000000000..060fabef5d --- /dev/null +++ b/include/internal/quic_error.h @@ -0,0 +1,38 @@ +/* + * 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_QUIC_ERROR_H +# define OSSL_QUIC_ERROR_H + +# include <openssl/ssl.h> + +/* RFC 9000 Section 20.1 */ +# define QUIC_ERR_NO_ERROR 0x00 +# define QUIC_ERR_INTERNAL_ERROR 0x01 +# define QUIC_ERR_CONNECTION_REFUSED 0x02 +# define QUIC_ERR_FLOW_CONTROL_ERROR 0x03 +# define QUIC_ERR_STREAM_LIMIT_ERROR 0x04 +# define QUIC_ERR_STREAM_STATE_ERROR 0x05 +# define QUIC_ERR_FINAL_SIZE_ERROR 0x06 +# define QUIC_ERR_FRAME_ENCODING_ERROR 0x07 +# define QUIC_ERR_TRANSPORT_PARAMETER_ERROR 0x08 +# define QUIC_ERR_CONNECTION_ID_LIMIT_ERROR 0x09 +# define QUIC_ERR_PROTOCOL_VIOLATION 0x0A +# define QUIC_ERR_INVALID_TOKEN 0x0B +# define QUIC_ERR_APPLICATION_ERROR 0x0C +# define QUIC_ERR_CRYPTO_BUFFER_EXCEEDED 0x0D +# define QUIC_ERR_KEY_UPDATE_ERROR 0x0E +# define QUIC_ERR_AEAD_LIMIT_REACHED 0x0F +# define QUIC_ERR_NO_VIABLE_PATH 0x10 + +/* Inclusive range for handshake-specific errors. */ +# define QUIC_ERR_CRYPTO_ERR_BEGIN 0x0100 +# define QUUC_ERR_CRYPTO_ERR_END 0x01FF + +#endif diff --git a/include/internal/quic_fc.h b/include/internal/quic_fc.h new file mode 100644 index 0000000000..20c18b5e1b --- /dev/null +++ b/include/internal/quic_fc.h @@ -0,0 +1,256 @@ +/* + * 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_QUIC_FC_H +# define OSSL_QUIC_FC_H + +# include <openssl/ssl.h> +# include "internal/time.h" + +/* + * TX Flow Controller (TXFC) + * ========================= + * + * For discussion, see doc/designs/quic-design/quic-fc.md. + */ +typedef struct quic_txfc_st QUIC_TXFC; + +struct quic_txfc_st { + QUIC_TXFC *parent; /* stream-level iff non-NULL */ + uint64_t swm, cwm; + char has_become_blocked; +}; + +/* + * Initialises a TX flow controller. conn_txfc should be non-NULL and point to + * the connection-level flow controller if the TXFC is for stream-level flow + * control, and NULL otherwise. + */ +int ossl_quic_txfc_init(QUIC_TXFC *txfc, QUIC_TXFC *conn_txfc); + +/* + * Gets the parent (i.e., connection-level) TX flow controller. Returns NULL if + * called on a connection-level TX flow controller. + */ +QUIC_TXFC *ossl_quic_txfc_get_parent(QUIC_TXFC *txfc); + +/* + * Bump the credit watermark (CWM) value. This is the 'On TX Window Updated' + * operation. This function is a no-op if it has already been called with an + * equal or higher CWM value. + * + * It returns 1 iff the call resulted in the CWM being bumped and 0 if it was + * not increased because it has already been called with an equal or higher CWM + * value. This is not an error per se but may indicate a local programming error + * or a protocol error in a remote peer. + */ +int ossl_quic_txfc_bump_cwm(QUIC_TXFC *txfc, uint64_t cwm); + +/* + * Get the number of bytes by which we are in credit. This is the number of + * controlled bytes we are allowed to send. (Thus if this function returns 0, we + * are currently blocked.) + * + * If called on a stream-level TXFC, ossl_quic_txfc_get_credit is called on + * the connection-level TXFC as well, and the lesser of the two values is + * returned. + */ +uint64_t ossl_quic_txfc_get_credit(QUIC_TXFC *txfc); + +/* + * Like ossl_quic_txfc_get_credit(), but when called on a stream-level TXFC, + * retrieves only the stream-level credit value and does not clamp it based on + * connection-level flow control. + */ +uint64_t ossl_quic_txfc_get_credit_local(QUIC_TXFC *txfc); + +/* + * Consume num_bytes of credit. This is the 'On TX' operation. This should be + * called when we transmit any controlled bytes. Calling this with an argument + * of 0 is a no-op. + * + * We must never transmit more controlled bytes than we are in credit for (see + * the return value of ossl_quic_txfc_get_credit()). If you call this function + * with num_bytes greater than our current credit, this function consumes the + * remainder of the credit and returns 0. This indicates a serious programming + * error on the caller's part. Otherwise, the function returns 1. + * + * If called on a stream-level TXFC, ossl_quic_txfc_consume_credit() is called + * on the connection-level TXFC also. If the call to that function on the + * connection-level TXFC returns zero, this function will also return zero. + */ +int ossl_quic_txfc_consume_credit(QUIC_TXFC *txfc, uint64_t num_bytes); + +/* + * Like ossl_quic_txfc_consume_credit(), but when called on a stream-level TXFC, + * consumes only from the stream-level credit and does not inform the + * connection-level TXFC. + */ +int ossl_quic_txfc_consume_credit_local(QUIC_TXFC *txfc, uint64_t num_bytes); + +/* + * This flag is provided for convenience. A caller is not required to use it. It + * is a boolean flag set whenever our credit drops to zero. If clear is 1, the + * flag is cleared. The old value of the flag is returned. Callers may use this + * to determine if they need to send a DATA_BLOCKED or STREAM_DATA_BLOCKED + * frame, which should contain the value returned by ossl_quic_txfc_get_cwm(). + */ +int ossl_quic_txfc_has_become_blocked(QUIC_TXFC *txfc, int clear); + +/* + * Get the current CWM value. This is mainly only needed when generating a + * DATA_BLOCKED or STREAM_DATA_BLOCKED frame, or for diagnostic purposes. + */ +uint64_t ossl_quic_txfc_get_cwm(QUIC_TXFC *txfc); + +/* + * Get the current spent watermark (SWM) value. This is purely for diagnostic + * use and should not be needed in normal circumstances. + */ +uint64_t ossl_quic_txfc_get_swm(QUIC_TXFC *txfc); + +/* + * RX Flow Controller (RXFC) + * ========================= + */ +typedef struct quic_rxfc_st QUIC_RXFC; + +struct quic_rxfc_st { + /* + * swm is the sent/received watermark, which tracks how much we have + * received from the peer. rwm is the retired watermark, which tracks how + * much has been passed to the application. esrwm is the rwm value at which + * the current auto-tuning epoch started. hwm is the highest stream length + * (STREAM frame offset + payload length) we have seen from a STREAM frame + * yet. + */ + uint64_t cwm, swm, rwm, esrwm, hwm, cur_window_size, max_window_size; + OSSL_TIME epoch_start; + OSSL_TIME (*now)(void *arg); + void *now_arg; + QUIC_RXFC *parent; + unsigned char error_code, has_cwm_changed, is_fin; +}; + +/* + * Initialises an RX flow controller. conn_rxfc should be non-NULL and point to + * a connection-level RXFC if the RXFC is for stream-level flow control, and + * NULL otherwise. initial_window_size and max_window_size specify the initial + * and absolute maximum window sizes, respectively. Window size values are + * expressed in bytes and determine how much credit the RXFC extends to the peer + * to transmit more data at a time. + */ +int ossl_quic_rxfc_init(QUIC_RXFC *rxfc, QUIC_RXFC *conn_rxfc, + uint64_t initial_window_size, + uint64_t max_window_size, + OSSL_TIME (*now)(void *arg), + void *now_arg); + +/* + * Gets the parent (i.e., connection-level) RXFC. Returns NULL if called on a + * connection-level RXFC. + */ +QUIC_RXFC *ossl_quic_rxfc_get_parent(QUIC_RXFC *rxfc); + +/* + * Changes the current maximum window size value. + */ +void ossl_quic_rxfc_set_max_window_size(QUIC_RXFC *rxfc, + size_t max_window_size); + +/* + * To be called whenever a STREAM frame is received. + * + * end is the value (offset + len), where offset is the offset field of the + * STREAM frame and len is the length of the STREAM frame's payload in bytes. + * + * is_fin should be 1 if the STREAM frame had the FIN flag set and 0 otherwise. + * + * conn_rxfc should point to a connection-level RXFC, which will have its state + * updated correctly by the stream-level RXFC. + * + * This function may be used on a stream-level RXFC only. + * + * You should check ossl_quic_rxfc_has_error() on both connection-level and + * stream-level RXFCs after calling this function, as an incoming STREAM frame + * may cause flow control limits to be exceeded by an errant peer. This + * function still returns 1 in this case, as this is not a caller error. + * + * Returns 1 on success or 0 on failure. + */ +int ossl_quic_rxfc_on_rx_stream_frame(QUIC_RXFC *rxfc, + uint64_t end, int is_fin); + +/* + * To be called whenever controlled bytes are retired, i.e. when bytes are + * dequeued from a QUIC stream and passed to the application. num_bytes + * is the number of bytes which were passed to the application. + * + * You should call this only on a stream-level RXFC. This function will update + * the connection-level RXFC automatically. + * + * rtt should be the current best understanding of the RTT to the peer, as + * offered by the Statistics Manager. + * + * You should check ossl_quic_rxfc_has_cwm_changed() after calling this + * function, as it may have caused the RXFC to decide to grant more flow control + * credit to the peer. + * + * Returns 1 on success and 0 on failure. + */ +int ossl_quic_rxfc_on_retire(QUIC_RXFC *rxfc, + uint64_t num_bytes, + OSSL_TIME rtt); + +/* + * Returns the current CWM which the RXFC thinks the peer should have. + * + * Note that the RXFC will increase this value in response to events, at which + * time a MAX_DATA or MAX_STREAM_DATA frame must be generated. Use + * ossl_quic_rxfc_has_cwm_changed() to detect this condition. + * + * This value increases monotonically. + */ +uint64_t ossl_quic_rxfc_get_cwm(QUIC_RXFC *rxfc); + +/* + * Returns the current SWM. This is the total number of bytes the peer has + * transmitted to us. This is intended for diagnostic use only; you should + * not need it. + */ +uint64_t ossl_quic_rxfc_get_swm(QUIC_RXFC *rxfc); + +/* + * Returns the current RWM. This is the total number of bytes that has been + * retired. This is intended for diagnostic use only; you should not need it. + */ +uint64_t ossl_quic_rxfc_get_rwm(QUIC_RXFC *rxfc); + +/* + * Returns the CWM changed flag. If clear is 1, the flag is cleared and the old + * value is returned. + */ +int ossl_quic_rxfc_has_cwm_changed(QUIC_RXFC *rxfc, int clear); + +/* + * Returns a QUIC_ERR_* error code if a flow control error has been detected. + * Otherwise, returns QUIC_ERR_NO_ERROR. If clear is 1, the error is cleared + * and the old value is returned. + * + * May return one of the following values: + * + * QUIC_ERR_FLOW_CONTROL_ERROR: + * This indicates a flow control protocol violation by the remote peer; the + * connection should be terminated in this event. + * QUIC_ERR_FINAL_SIZE: + * The peer attempted to change the stream length after ending the stream. + */ +int ossl_quic_rxfc_get_error(QUIC_RXFC *rxfc, int clear); + +#endif |