include/internal/quic_lcidm.h

   1 /*
   2 * Copyright 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
  10 #ifndef OSSL_INTERNAL_QUIC_LCIDM_H
  11 # define OSSL_INTERNAL_QUIC_LCIDM_H
  12 # pragma once
  13
  14 # include "internal/e_os.h"
  15 # include "internal/time.h"
  16 # include "internal/quic_types.h"
  17 # include "internal/quic_wire.h"
  18 # include "internal/quic_predef.h"
  19
  20 # ifndef OPENSSL_NO_QUIC
  21
  22 /*
  23  * QUIC Local Connection ID Manager
  24  * ================================
  25  *
  26  * This manages connection IDs for the RX side, which is to say that it issues
  27  * local CIDs (LCIDs) to a peer which that peer can then use to address us via a
  28  * packet DCID. This is as opposed to CID management for the TX side, which
  29  * determines which CIDs we use to transmit based on remote CIDs (RCIDs) the
  30  * peer sent to us.
  31  *
  32  * An opaque pointer can be associated with each LCID. Pointer identity
  33  * (equality) is used to distinguish distinct connections.
  34  *
  35  * LCIDs fall into three categories:
  36  *
  37  *   1. A client's Initial ODCID                       (1)
  38  *   2. Our local Initial SCID                         (1)
  39  *   3. A CID issued via a NEW_CONNECTION_ID frame     (n)
  40  *   4. A server's Retry SCID                          (0..1)
  41  *
  42  * (1) is enrolled using ossl_quic_lcidm_enrol_odcid() and retired by the time
  43  * of handshake completion at the latest. It is needed in case the first
  44  * response packet from a server is lost and the client keeps using its Initial
  45  * ODCID. There is never more than one of these, and no sequence number is
  46  * associated with this temporary LCID.
  47  *
  48  * (2) is created by a client when it begins connecting, or by a server when it
  49  * responds to a new connection request. In the latter case, it is generated by
  50  * the server as the preferred DCID for traffic directed towards it. A client
  51  * should switch to using this as a RCID as soon as it receives a valid packet
  52  * from the server. This LCID has a sequence number of 0.
  53  *
  54  * (3) is created when we issue a NEW_CONNECTION_ID frame. Arbitrarily many of
  55  * these can exist.
  56  *
  57  * (4) is a special case. When a server issues a retry it generates a new SCID
  58  * much as it does for (2). However since retries are supposed to be stateless,
  59  * we don't actually register it as an LCID. When the client subsequently
  60  * replies with an Initial packet with token in response to the Retry, the
  61  * server will handle this as a new connection attempt due to not recognising
  62  * the DCID, which is what we want anyway. (The Retry SCID is subsequently
  63  * validated as matching the new Initial ODCID via attestation in the encrypted
  64  * contents of the opaque retry token.) Thus, the LCIDM is not actually involved
  65  * at all here.
  66  *
  67  * Retirement is as follows:
  68  *
  69  * (1) is retired automatically when we know it won't be needed anymore. This is
  70  * when the handshake is completed at the latest, and could potentially be
  71  * earlier.
  72  *
  73  * Both (2) and (3) are retired normally via RETIRE_CONNECTION_ID frames, as it
  74  * has a sequence number of 0.
  75  *
  76  *
  77  * ODCID Peculiarities
  78  * -------------------
  79  *
  80  * Almost all LCIDs are issued by the receiver responsible for routing them,
  81  * which means that almost all LCIDs will have the same length (specified in
  82  * lcid_len below). The only exception to this is (1); the ODCID is the only
  83  * case where we recognise an LCID we didn't ourselves generate. Since an ODCID
  84  * is chosen by the peer, it can be any length and doesn't necessarily match the
  85  * length we use for LCIDs we generate ourselves.
  86  *
  87  * Since DCID decoding for short-header packets requires an implicitly known
  88  * DCID length, it logically follows that an ODCID can never be used in a 1-RTT
  89  * packet. This is fine as by the time the 1-RTT EL is reached the peer should
  90  * already have switched away from the ODCID to a CID we generated ourselves,
  91  * and if this has not happened we can consider that a protocol violation.
  92  *
  93  * In any case, this means that the LCIDM must necessarily support LCIDs of
  94  * different lengths, even if it always generates LCIDs of a given length.
  95  *
  96  * An ODCID has no sequence number associated with it. It is the only CID to
  97  * lack one.
  98  */
  99
 100 /*
 101  * Creates a new LCIDM. lcid_len is the length to use for LCIDs in bytes, which
 102  * may be zero.
 103  *
 104  * Returns NULL on failure.
 105  */
 106 QUIC_LCIDM *ossl_quic_lcidm_new(OSSL_LIB_CTX *libctx, size_t lcid_len);
 107
 108 /* Frees a LCIDM. */
 109 void ossl_quic_lcidm_free(QUIC_LCIDM *lcidm);
 110
 111 /* Gets the local CID length this LCIDM was configured to use. */
 112 size_t ossl_quic_lcidm_get_lcid_len(const QUIC_LCIDM *lcidm);
 113
 114 /*
 115  * Determines the number of active LCIDs (i.e,. LCIDs which can be used for
 116  * reception) currently associated with the given opaque pointer.
 117  */
 118 size_t ossl_quic_lcidm_get_num_active_lcid(const QUIC_LCIDM *lcidm,
 119                                            void *opaque);
 120
 121 /*
 122  * Enrol an Initial ODCID sent by the peer. This is the DCID in the first
 123  * Initial packet sent by a client. When we receive a client's first Initial
 124  * packet, we immediately respond with our own SCID (generated using
 125  * ossl_quic_lcidm_generate_initial) to tell the client to switch to using that,
 126  * so ideally the ODCID will only be used for a single packet. However since
 127  * that response might be lost, we also need to accept additional packets using
 128  * the ODCID and need to make sure they get routed to the same connection and
 129  * not interpreted as another new connection attempt. Thus before the CID
 130  * switchover is confirmed, we also have to handle incoming packets addressed to
 131  * the ODCID. This function is used to temporarily enroll the ODCID for a
 132  * connection. Such a LCID is considered to have a sequence number of
 133  * LCIDM_ODCID_SEQ_NUM internally for our purposes.
 134  *
 135  * Note that this is the *only* circumstance where we recognise an LCID we did
 136  * not generate ourselves, or allow an LCID with a different length to lcid_len.
 137  *
 138  * An ODCID MUST be at least 8 bytes in length (RFC 9000 s. 7.2).
 139  *
 140  * This function may only be called once for a given connection.
 141  * Returns 1 on success or 0 on failure.
 142  */
 143 int ossl_quic_lcidm_enrol_odcid(QUIC_LCIDM *lcidm, void *opaque,
 144                                 const QUIC_CONN_ID *initial_odcid);
 145
 146 /*
 147  * Retire a previously enrolled ODCID for a connection. This is generally done
 148  * when we know the peer won't be using it any more (when the handshake is
 149  * completed at the absolute latest, possibly earlier).
 150  *
 151  * Returns 1 if there was an enrolled ODCID which was retired and 0 if there was
 152  * not or on other failure.
 153  */
 154 int ossl_quic_lcidm_retire_odcid(QUIC_LCIDM *lcidm, void *opaque);
 155
 156 /*
 157  * Create the first LCID for a given opaque pointer. The generated LCID is
 158  * written to *initial_lcid and associated with the given opaque pointer.
 159  *
 160  * After this function returns successfully, the caller can for example
 161  * register the new LCID with a DEMUX.
 162  *
 163  * May not be called more than once for a given opaque pointer value.
 164  */
 165 int ossl_quic_lcidm_generate_initial(QUIC_LCIDM *lcidm,
 166                                      void *opaque,
 167                                      QUIC_CONN_ID *initial_lcid);
 168
 169 /*
 170  * Create a subsequent LCID for a given opaque pointer. The information needed
 171  * for a NEW_CONN_ID frame informing the peer of the new LCID, including the
 172  * LCID itself, is written to *ncid_frame.
 173  *
 174  * ncid_frame->stateless_reset is not initialised and the caller is responsible
 175  * for setting it.
 176  *
 177  * After this function returns successfully, the caller can for example
 178  * register the new LCID with a DEMUX and queue the NEW_CONN_ID frame.
 179  */
 180 int ossl_quic_lcidm_generate(QUIC_LCIDM *lcidm,
 181                              void *opaque,
 182                              OSSL_QUIC_FRAME_NEW_CONN_ID *ncid_frame);
 183
 184 /*
 185  * Retire up to one LCID for a given opaque pointer value. Called repeatedly to
 186  * handle a RETIRE_CONN_ID frame.
 187  *
 188  * If containing_pkt_dcid is non-NULL, this function enforces the requirement
 189  * that a CID not be retired by a packet using that CID as the DCID. If
 190  * containing_pkt_dcid is NULL, this check is skipped.
 191  *
 192  * If a LCID is retired as a result of a call to this function, the LCID which
 193  * was retired is written to *retired_lcid, the sequence number of the LCID is
 194  * written to *retired_seq_num and *did_retire is set to 1. Otherwise,
 195  * *did_retire is set to 0. This enables a caller to e.g. unregister the LCID
 196  * from a DEMUX. A caller should call this function repeatedly until the
 197  * function returns with *did_retire set to 0.
 198  *
 199  * This call is likely to cause the value returned by
 200  * ossl_quic_lcidm_get_num_active_lcid() to go down. A caller may wish to call
 201  * ossl_quic_lcidm_generate() repeatedly to bring the number of active LCIDs
 202  * back up to some threshold in response after calling this function.
 203  *
 204  * Returns 1 on success and 0 on failure. If arguments are valid but zero LCIDs
 205  * are retired, this is considered a success condition.
 206  */
 207 int ossl_quic_lcidm_retire(QUIC_LCIDM *lcidm,
 208                            void *opaque,
 209                            uint64_t retire_prior_to,
 210                            const QUIC_CONN_ID *containing_pkt_dcid,
 211                            QUIC_CONN_ID *retired_lcid,
 212                            uint64_t *retired_seq_num,
 213                            int *did_retire);
 214
 215 /*
 216  * Cull all LCIDM state relating to a given opaque pointer value. This is useful
 217  * if connection state is spontaneously freed. The caller is responsible for
 218  * e.g. DEMUX state updates.
 219  */
 220 int ossl_quic_lcidm_cull(QUIC_LCIDM *lcidm, void *opaque);
 221
 222 /*
 223  * Lookup a LCID. If the LCID is found, writes the associated opaque pointer to
 224  * *opaque and the associated sequence number to *seq_num. Returns 1 on success
 225  * and 0 if an entry is not found. An output argument may be set to NULL if its
 226  * value is not required.
 227  *
 228  * If the LCID is for an Initial ODCID, *seq_num is set to
 229  * LCIDM_ODCID_SEQ_NUM.
 230  */
 231 #define LCIDM_ODCID_SEQ_NUM     UINT64_MAX
 232
 233 int ossl_quic_lcidm_lookup(QUIC_LCIDM *lcidm,
 234                            const QUIC_CONN_ID *lcid,
 235                            uint64_t *seq_num,
 236                            void **opaque);
 237
 238 /*
 239  * Debug call to manually remove a specific LCID. Should not be needed in normal
 240  * usage. Returns 1 if the LCID was successfully found and removed and 0
 241  * otherwise.
 242  */
 243 int ossl_quic_lcidm_debug_remove(QUIC_LCIDM *lcidm,
 244                                  const QUIC_CONN_ID *lcid);
 245
 246 /*
 247  * Debug call to manually add a numbered LCID with a specific CID value and
 248  * sequence number. Should not be needed in normal usage. Returns 1 on success
 249  * and 0 on failure.
 250  */
 251 int ossl_quic_lcidm_debug_add(QUIC_LCIDM *lcidm, void *opaque,
 252                               const QUIC_CONN_ID *lcid,
 253                               uint64_t seq_num);
 254
 255 # endif
 256
 257 #endif