include/internal/quic_engine.h

   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