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