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