xref: /freebsd/crypto/openssl/include/internal/quic_engine.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 #ifndef OSSL_QUIC_ENGINE_H
10*e7be843bSPierre Pronchery # define OSSL_QUIC_ENGINE_H
11*e7be843bSPierre Pronchery 
12*e7be843bSPierre Pronchery # include <openssl/ssl.h>
13*e7be843bSPierre Pronchery 
14*e7be843bSPierre Pronchery # include "internal/quic_predef.h"
15*e7be843bSPierre Pronchery # include "internal/quic_port.h"
16*e7be843bSPierre Pronchery # include "internal/thread_arch.h"
17*e7be843bSPierre Pronchery 
18*e7be843bSPierre Pronchery # ifndef OPENSSL_NO_QUIC
19*e7be843bSPierre Pronchery 
20*e7be843bSPierre Pronchery /*
21*e7be843bSPierre Pronchery  * QUIC Engine
22*e7be843bSPierre Pronchery  * ===========
23*e7be843bSPierre Pronchery  *
24*e7be843bSPierre Pronchery  * A QUIC Engine (QUIC_ENGINE) represents an event processing domain for the
25*e7be843bSPierre Pronchery  * purposes of QUIC and contains zero or more subsidiary QUIC_PORT instances
26*e7be843bSPierre Pronchery  * (each of which currently represents a UDP socket), each of which in turn
27*e7be843bSPierre Pronchery  * contains zero or more subsidiary QUIC_CHANNEL instances, each of which
28*e7be843bSPierre Pronchery  * represents a single QUIC connection. All QUIC_PORT instances must belong
29*e7be843bSPierre Pronchery  * to a QUIC_ENGINE.
30*e7be843bSPierre Pronchery  *
31*e7be843bSPierre Pronchery  * TODO(QUIC FUTURE): Currently a QUIC_PORT belongs to a single QUIC_CHANNEL.
32*e7be843bSPierre Pronchery  * This will cease to be the case once connection migration and/or multipath is
33*e7be843bSPierre Pronchery  * implemented, so in future a channel might be associated with multiple ports.
34*e7be843bSPierre Pronchery  *
35*e7be843bSPierre Pronchery  * A QUIC engine is the root object in a QUIC event domain, and is responsible
36*e7be843bSPierre Pronchery  * for managing event processing for all QUIC ports and channels (e.g. timeouts,
37*e7be843bSPierre Pronchery  * clock management, the QUIC_REACTOR instance, etc.).
38*e7be843bSPierre Pronchery  */
39*e7be843bSPierre Pronchery typedef struct quic_engine_args_st {
40*e7be843bSPierre Pronchery     OSSL_LIB_CTX    *libctx;
41*e7be843bSPierre Pronchery     const char      *propq;
42*e7be843bSPierre Pronchery 
43*e7be843bSPierre Pronchery     /*
44*e7be843bSPierre Pronchery      * This must be a mutex the lifetime of which will exceed that of the engine
45*e7be843bSPierre Pronchery      * and all ports and channels. The instantiator of the engine is responsible
46*e7be843bSPierre Pronchery      * for providing a mutex as this makes it easier to handle instantiation and
47*e7be843bSPierre Pronchery      * teardown of channels in situations potentially requiring locking.
48*e7be843bSPierre Pronchery      *
49*e7be843bSPierre Pronchery      * Note that this is a MUTEX not a RWLOCK as it needs to be an OS mutex for
50*e7be843bSPierre Pronchery      * compatibility with an OS's condition variable wait API, whereas RWLOCK
51*e7be843bSPierre Pronchery      * may, depending on the build configuration, be implemented using an OS's
52*e7be843bSPierre Pronchery      * mutex primitive or using its RW mutex primitive.
53*e7be843bSPierre Pronchery      */
54*e7be843bSPierre Pronchery     CRYPTO_MUTEX    *mutex;
55*e7be843bSPierre Pronchery 
56*e7be843bSPierre Pronchery     /* Flags to pass when initialising the reactor. */
57*e7be843bSPierre Pronchery     uint64_t        reactor_flags;
58*e7be843bSPierre Pronchery } QUIC_ENGINE_ARGS;
59*e7be843bSPierre Pronchery 
60*e7be843bSPierre Pronchery QUIC_ENGINE *ossl_quic_engine_new(const QUIC_ENGINE_ARGS *args);
61*e7be843bSPierre Pronchery 
62*e7be843bSPierre Pronchery void ossl_quic_engine_free(QUIC_ENGINE *qeng);
63*e7be843bSPierre Pronchery 
64*e7be843bSPierre Pronchery /*
65*e7be843bSPierre Pronchery  * Create a port which is a child of the engine. args->engine shall be NULL.
66*e7be843bSPierre Pronchery  */
67*e7be843bSPierre Pronchery QUIC_PORT *ossl_quic_engine_create_port(QUIC_ENGINE *qeng,
68*e7be843bSPierre Pronchery                                         const QUIC_PORT_ARGS *args);
69*e7be843bSPierre Pronchery 
70*e7be843bSPierre Pronchery /* Gets the mutex used by the engine. */
71*e7be843bSPierre Pronchery CRYPTO_MUTEX *ossl_quic_engine_get0_mutex(QUIC_ENGINE *qeng);
72*e7be843bSPierre Pronchery 
73*e7be843bSPierre Pronchery /* Gets the current time. */
74*e7be843bSPierre Pronchery OSSL_TIME ossl_quic_engine_get_time(QUIC_ENGINE *qeng);
75*e7be843bSPierre Pronchery 
76*e7be843bSPierre Pronchery /*
77*e7be843bSPierre Pronchery  * Some use cases really need actual time rather than "fake" time. Convert a
78*e7be843bSPierre Pronchery  * fake time into a real time. If tm is before the current fake time then the
79*e7be843bSPierre Pronchery  * current time is returned.
80*e7be843bSPierre Pronchery  */
81*e7be843bSPierre Pronchery OSSL_TIME ossl_quic_engine_make_real_time(QUIC_ENGINE *qeng, OSSL_TIME tm);
82*e7be843bSPierre Pronchery 
83*e7be843bSPierre Pronchery /* Override the callback for getting the current time */
84*e7be843bSPierre Pronchery void ossl_quic_engine_set_time_cb(QUIC_ENGINE *qeng,
85*e7be843bSPierre Pronchery                                   OSSL_TIME (*now_cb)(void *arg),
86*e7be843bSPierre Pronchery                                   void *now_cb_arg);
87*e7be843bSPierre Pronchery 
88*e7be843bSPierre Pronchery /* For testing use. While enabled, ticking is not performed. */
89*e7be843bSPierre Pronchery void ossl_quic_engine_set_inhibit_tick(QUIC_ENGINE *qeng, int inhibit);
90*e7be843bSPierre Pronchery 
91*e7be843bSPierre Pronchery /* Gets the reactor which can be used to tick/poll on the port. */
92*e7be843bSPierre Pronchery QUIC_REACTOR *ossl_quic_engine_get0_reactor(QUIC_ENGINE *qeng);
93*e7be843bSPierre Pronchery 
94*e7be843bSPierre Pronchery OSSL_LIB_CTX *ossl_quic_engine_get0_libctx(QUIC_ENGINE *qeng);
95*e7be843bSPierre Pronchery const char *ossl_quic_engine_get0_propq(QUIC_ENGINE *qeng);
96*e7be843bSPierre Pronchery 
97*e7be843bSPierre Pronchery /*
98*e7be843bSPierre Pronchery  * Look through all the engine's ports and determine if any of them have had a
99*e7be843bSPierre Pronchery  * BIO changed. If so, update the blocking support detection data in the
100*e7be843bSPierre Pronchery  * QUIC_REACTOR. If force is 1, always do the update even if nothing seems
101*e7be843bSPierre Pronchery  * to have changed.
102*e7be843bSPierre Pronchery  */
103*e7be843bSPierre Pronchery void ossl_quic_engine_update_poll_descriptors(QUIC_ENGINE *qeng, int force);
104*e7be843bSPierre Pronchery 
105*e7be843bSPierre Pronchery # endif
106*e7be843bSPierre Pronchery 
107*e7be843bSPierre Pronchery #endif
108