include/internal/quic_ackm.h

   1 /*
   2  * Copyright 2022-2023 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 #ifndef OSSL_QUIC_ACKM_H
  10 # define OSSL_QUIC_ACKM_H
  11
  12 # include "internal/quic_statm.h"
  13 # include "internal/quic_cc.h"
  14 # include "internal/quic_types.h"
  15 # include "internal/quic_wire.h"
  16 # include "internal/quic_predef.h"
  17 # include "internal/time.h"
  18 # include "internal/list.h"
  19
  20 # ifndef OPENSSL_NO_QUIC
  21
  22 OSSL_ACKM *ossl_ackm_new(OSSL_TIME (*now)(void *arg),
  23                          void *now_arg,
  24                          OSSL_STATM *statm,
  25                          const OSSL_CC_METHOD *cc_method,
  26                          OSSL_CC_DATA *cc_data);
  27 void ossl_ackm_free(OSSL_ACKM *ackm);
  28
  29 void ossl_ackm_set_loss_detection_deadline_callback(OSSL_ACKM *ackm,
  30                                                     void (*fn)(OSSL_TIME deadline,
  31                                                                void *arg),
  32                                                     void *arg);
  33
  34 void ossl_ackm_set_ack_deadline_callback(OSSL_ACKM *ackm,
  35                                          void (*fn)(OSSL_TIME deadline,
  36                                                     int pkt_space,
  37                                                     void *arg),
  38                                          void *arg);
  39
  40 /*
  41  * Configures the RX-side maximum ACK delay. This is the maximum amount of time
  42  * the peer is allowed to delay sending an ACK frame after receiving an
  43  * ACK-eliciting packet. The peer communicates this value via a transport
  44  * parameter and it must be provided to the ACKM.
  45  */
  46 void ossl_ackm_set_rx_max_ack_delay(OSSL_ACKM *ackm, OSSL_TIME rx_max_ack_delay);
  47
  48 /*
  49  * Configures the TX-side maximum ACK delay. This is the maximum amount of time
  50  * we are allowed to delay sending an ACK frame after receiving an ACK-eliciting
  51  * packet. Note that this cannot be changed after a connection is established as
  52  * it must be accurately reported in the transport parameters we send to our
  53  * peer.
  54  */
  55 void ossl_ackm_set_tx_max_ack_delay(OSSL_ACKM *ackm, OSSL_TIME tx_max_ack_delay);
  56
  57 typedef struct ossl_ackm_tx_pkt_st OSSL_ACKM_TX_PKT;
  58 struct ossl_ackm_tx_pkt_st {
  59     /* The packet number of the transmitted packet. */
  60     QUIC_PN pkt_num;
  61
  62     /* The number of bytes in the packet which was sent. */
  63     size_t num_bytes;
  64
  65     /* The time at which the packet was sent. */
  66     OSSL_TIME time;
  67
  68     /*
  69      * If the packet being described by this structure contains an ACK frame,
  70      * this must be set to the largest PN ACK'd by that frame.
  71      *
  72      * Otherwise, it should be set to QUIC_PN_INVALID.
  73      *
  74      * This is necessary to bound the number of PNs we have to keep track of on
  75      * the RX side (RFC 9000 s. 13.2.4). It allows older PN tracking information
  76      * on the RX side to be discarded.
  77      */
  78     QUIC_PN largest_acked;
  79
  80     /*
  81      * One of the QUIC_PN_SPACE_* values. This qualifies the pkt_num field
  82      * into a packet number space.
  83      */
  84     unsigned int pkt_space :2;
  85
  86     /*
  87      * 1 if the packet is in flight. A packet is considered 'in flight' if it is
  88      * counted for purposes of congestion control and 'bytes in flight' counts.
  89      * Most packets are considered in flight. The only circumstance where a
  90      * numbered packet is not considered in flight is if it contains only ACK
  91      * frames (not even PADDING frames), as these frames can bypass CC.
  92      */
  93     unsigned int is_inflight :1;
  94
  95     /*
  96      * 1 if the packet has one or more ACK-eliciting frames.
  97      * Note that if this is set, is_inflight must be set.
  98      */
  99     unsigned int is_ack_eliciting :1;
 100
 101     /* 1 if the packet is a PTO probe. */
 102     unsigned int is_pto_probe :1;
 103
 104     /* 1 if the packet is an MTU probe. */
 105     unsigned int is_mtu_probe :1;
 106
 107     /* Callback called if frames in this packet are lost. arg is cb_arg. */
 108     void (*on_lost)(void *arg);
 109     /* Callback called if frames in this packet are acked. arg is cb_arg. */
 110     void (*on_acked)(void *arg);
 111     /*
 112      * Callback called if frames in this packet are neither acked nor lost. arg
 113      * is cb_arg.
 114      */
 115     void (*on_discarded)(void *arg);
 116     void  *cb_arg;
 117
 118     /*
 119      * (Internal use fields; must be zero-initialized.)
 120      *
 121      * Keep a TX history list, anext is used to manifest
 122      * a singly-linked list of newly-acknowledged packets, and lnext is used to
 123      * manifest a singly-linked list of newly lost packets.
 124      */
 125     OSSL_LIST_MEMBER(tx_history, OSSL_ACKM_TX_PKT);
 126
 127     struct ossl_ackm_tx_pkt_st *anext;
 128     struct ossl_ackm_tx_pkt_st *lnext;
 129 };
 130
 131 int ossl_ackm_on_tx_packet(OSSL_ACKM *ackm, OSSL_ACKM_TX_PKT *pkt);
 132 int ossl_ackm_on_rx_datagram(OSSL_ACKM *ackm, size_t num_bytes);
 133
 134 #  define OSSL_ACKM_ECN_NONE      0
 135 #  define OSSL_ACKM_ECN_ECT1      1
 136 #  define OSSL_ACKM_ECN_ECT0      2
 137 #  define OSSL_ACKM_ECN_ECNCE     3
 138
 139 typedef struct ossl_ackm_rx_pkt_st {
 140     /* The packet number of the received packet. */
 141     QUIC_PN pkt_num;
 142
 143     /* The time at which the packet was received. */
 144     OSSL_TIME time;
 145
 146     /*
 147      * One of the QUIC_PN_SPACE_* values. This qualifies the pkt_num field
 148      * into a packet number space.
 149      */
 150     unsigned int pkt_space :2;
 151
 152     /* 1 if the packet has one or more ACK-eliciting frames. */
 153     unsigned int is_ack_eliciting :1;
 154
 155     /*
 156      * One of the OSSL_ACKM_ECN_* values. This is the ECN labelling applied to
 157      * the received packet. If unknown, use OSSL_ACKM_ECN_NONE.
 158      */
 159     unsigned int ecn :2;
 160 } OSSL_ACKM_RX_PKT;
 161
 162 int ossl_ackm_on_rx_packet(OSSL_ACKM *ackm, const OSSL_ACKM_RX_PKT *pkt);
 163
 164 int ossl_ackm_on_rx_ack_frame(OSSL_ACKM *ackm, const OSSL_QUIC_FRAME_ACK *ack,
 165                               int pkt_space, OSSL_TIME rx_time);
 166
 167 /*
 168  * Discards a PN space. This must be called for a PN space before freeing the
 169  * ACKM if you want in-flight packets to have their discarded callbacks called.
 170  * This should never be called in ordinary QUIC usage for the Application Data
 171  * PN space, but it may be called for the Application Data PN space prior to
 172  * freeing the ACKM to simplify teardown implementations.
 173  */
 174 int ossl_ackm_on_pkt_space_discarded(OSSL_ACKM *ackm, int pkt_space);
 175
 176 int ossl_ackm_on_handshake_confirmed(OSSL_ACKM *ackm);
 177 int ossl_ackm_on_timeout(OSSL_ACKM *ackm);
 178
 179 OSSL_TIME ossl_ackm_get_loss_detection_deadline(OSSL_ACKM *ackm);
 180
 181 /*
 182  * Generates an ACK frame, regardless of whether the ACK manager thinks
 183  * one should currently be sent.
 184  *
 185  * This clears the flag returned by ossl_ackm_is_ack_desired and the deadline
 186  * returned by ossl_ackm_get_ack_deadline.
 187  */
 188 const OSSL_QUIC_FRAME_ACK *ossl_ackm_get_ack_frame(OSSL_ACKM *ackm,
 189                                                    int pkt_space);
 190
 191 /*
 192  * Returns the deadline after which an ACK frame should be generated by calling
 193  * ossl_ackm_get_ack_frame, or OSSL_TIME_INFINITY if no deadline is currently
 194  * applicable. If the deadline has already passed, this function may return that
 195  * deadline, or may return OSSL_TIME_ZERO.
 196  */
 197 OSSL_TIME ossl_ackm_get_ack_deadline(OSSL_ACKM *ackm, int pkt_space);
 198
 199 /*
 200  * Returns 1 if the ACK manager thinks an ACK frame ought to be generated and
 201  * sent at this time. ossl_ackm_get_ack_frame will always provide an ACK frame
 202  * whether or not this returns 1, so it is suggested that you call this function
 203  * first to determine whether you need to generate an ACK frame.
 204  *
 205  * The return value of this function can change based on calls to
 206  * ossl_ackm_on_rx_packet and based on the passage of time (see
 207  * ossl_ackm_get_ack_deadline).
 208  */
 209 int ossl_ackm_is_ack_desired(OSSL_ACKM *ackm, int pkt_space);
 210
 211 /*
 212  * Returns 1 if the given RX PN is 'processable'. A processable PN is one that
 213  * is not either
 214  *
 215  *   - duplicate, meaning that we have already been passed such a PN in a call
 216  *     to ossl_ackm_on_rx_packet; or
 217  *
 218  *   - written off, meaning that the PN is so old we have stopped tracking state
 219  *     for it (meaning that we cannot tell whether it is a duplicate and cannot
 220  *     process it safely).
 221  *
 222  * This should be called for a packet before attempting to process its contents.
 223  * Failure to do so may result in processing a duplicated packet in violation of
 224  * the RFC.
 225  *
 226  * The return value of this function transitions from 1 to 0 for a given PN once
 227  * that PN is passed to ossl_ackm_on_rx_packet, thus this function must be used
 228  * before calling ossl_ackm_on_rx_packet.
 229  */
 230 int ossl_ackm_is_rx_pn_processable(OSSL_ACKM *ackm, QUIC_PN pn, int pkt_space);
 231
 232 typedef struct ossl_ackm_probe_info_st {
 233     /*
 234      * The following two probe request types are used only for anti-deadlock
 235      * purposes in relation to the anti-amplification logic, by generating
 236      * packets to buy ourselves more anti-amplification credit with the server
 237      * until a client address is verified. Note that like all Initial packets,
 238      * any Initial probes are padded.
 239      *
 240      * Note: The ACKM will only ever increase these by one at a time,
 241      * as only one probe packet should be generated for these cases.
 242      */
 243     uint32_t anti_deadlock_initial, anti_deadlock_handshake;
 244
 245     /*
 246      * Send an ACK-eliciting packet for each count here.
 247      *
 248      * Note: The ACKM may increase this by either one or two for each probe
 249      * request, depending on how many probe packets it thinks should be
 250      * generated.
 251      */
 252     uint32_t pto[QUIC_PN_SPACE_NUM];
 253 } OSSL_ACKM_PROBE_INFO;
 254
 255 /*
 256  * Returns a pointer to a structure counting any pending probe requests which
 257  * have been generated by the ACKM. The fields in the structure are incremented
 258  * by one every time the ACKM wants another probe of the given type to be sent.
 259  * If the ACKM thinks two packets should be generated for a probe, it will
 260  * increment the field twice.
 261  *
 262  * It is permissible for the caller to decrement or zero these fields to keep
 263  * track of when it has generated a probe as asked. The returned structure
 264  * has the same lifetime as the ACKM.
 265  *
 266  * This function should be called after calling e.g. ossl_ackm_on_timeout
 267  * to determine if any probe requests have been generated.
 268  */
 269 OSSL_ACKM_PROBE_INFO *ossl_ackm_get0_probe_request(OSSL_ACKM *ackm);
 270
 271 int ossl_ackm_get_largest_unacked(OSSL_ACKM *ackm, int pkt_space, QUIC_PN *pn);
 272
 273 /*
 274  * Forces the ACKM to consider a packet with the given PN in the given PN space
 275  * as having been pseudo-lost. The main reason to use this is during a Retry, to
 276  * force any resources sent in the first Initial packet to be resent.
 277  *
 278  * The lost callback is called for the packet, but the packet is NOT considered
 279  * lost for congestion control purposes. Thus this is not exactly the same as a
 280  * true loss situation.
 281  */
 282 int ossl_ackm_mark_packet_pseudo_lost(OSSL_ACKM *ackm,
 283                                       int pkt_space, QUIC_PN pn);
 284
 285 /*
 286  * Returns the PTO duration as currently calculated. This is a quantity of time.
 287  * This duration is used in various parts of QUIC besides the ACKM.
 288  */
 289 OSSL_TIME ossl_ackm_get_pto_duration(OSSL_ACKM *ackm);
 290
 291 /* Returns the largest acked PN in the given PN space. */
 292 QUIC_PN ossl_ackm_get_largest_acked(OSSL_ACKM *ackm, int pkt_space);
 293
 294 # endif
 295
 296 #endif