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 #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 SERVER): 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 OSSL_TIME (*now_cb)(void *arg); 57 void *now_cb_arg; 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 /* For testing use. While enabled, ticking is not performed. */ 77 void ossl_quic_engine_set_inhibit_tick(QUIC_ENGINE *qeng, int inhibit); 78 79 /* Gets the reactor which can be used to tick/poll on the port. */ 80 QUIC_REACTOR *ossl_quic_engine_get0_reactor(QUIC_ENGINE *qeng); 81 82 # endif 83 84 #endif 85