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