2 * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
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
10 #ifndef OSSL_QUIC_CHANNEL_H
11 # define OSSL_QUIC_CHANNEL_H
13 # include <openssl/ssl.h>
14 # include "internal/quic_types.h"
15 # include "internal/quic_stream_map.h"
16 # include "internal/quic_reactor.h"
17 # include "internal/quic_statm.h"
18 # include "internal/time.h"
20 # ifndef OPENSSL_NO_QUIC
26 * A QUIC channel (QUIC_CHANNEL) is an object which binds together all of the
27 * various pieces of QUIC into a single top-level object, and handles connection
28 * state which is not specific to the client or server roles. In particular, it
29 * is strictly separated from the libssl front end I/O API personality layer,
30 * and is not an SSL object.
32 * The name QUIC_CHANNEL is chosen because QUIC_CONNECTION is already in use,
33 * but functionally these relate to the same thing (a QUIC connection). The use
34 * of two separate objects ensures clean separation between the API personality
35 * layer and common code for handling connections, and between the functionality
36 * which is specific to clients and which is specific to servers, and the
37 * functionality which is common to both.
39 * The API personality layer provides SSL objects (e.g. a QUIC_CONNECTION) which
40 * consume a QUIC channel and implement a specific public API. Things which are
41 * handled by the API personality layer include emulation of blocking semantics,
42 * handling of SSL object mode flags like non-partial write mode, etc.
44 * Where the QUIC_CHANNEL is used in a server role, there is one QUIC_CHANNEL
45 * per connection. In the future a QUIC Channel Manager will probably be defined
46 * to handle ownership of resources which are shared between connections (e.g.
47 * demuxers). Since we only use server-side functionality for dummy test servers
48 * for now, which only need to handle one connection at a time, this is not
52 # define QUIC_CHANNEL_STATE_IDLE 0
53 # define QUIC_CHANNEL_STATE_ACTIVE 1
54 # define QUIC_CHANNEL_STATE_TERMINATING_CLOSING 2
55 # define QUIC_CHANNEL_STATE_TERMINATING_DRAINING 3
56 # define QUIC_CHANNEL_STATE_TERMINATED 4
58 typedef struct quic_channel_args_st
{
65 typedef struct quic_channel_st QUIC_CHANNEL
;
68 * Create a new QUIC channel using the given arguments. The argument structure
69 * does not need to remain allocated. Returns NULL on failure.
71 QUIC_CHANNEL
*ossl_quic_channel_new(const QUIC_CHANNEL_ARGS
*args
);
73 /* No-op if ch is NULL. */
74 void ossl_quic_channel_free(QUIC_CHANNEL
*ch
);
76 /* Set mutator callbacks for test framework support */
77 int ossl_quic_channel_set_mutator(QUIC_CHANNEL
*ch
,
78 ossl_mutate_packet_cb mutatecb
,
79 ossl_finish_mutate_cb finishmutatecb
,
83 * Connection Lifecycle Events
84 * ===========================
86 * Various events that can be raised on the channel by other parts of the QUIC
87 * implementation. Some of these are suitable for general use by any part of the
88 * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very
89 * specific use by particular components only (e.g.
90 * ossl_quic_channel_on_handshake_confirmed).
94 * To be used by a QUIC connection. Starts the channel. For a client-mode
95 * channel, this starts sending the first handshake layer message, etc. Can only
96 * be called in the idle state; successive calls are ignored.
98 int ossl_quic_channel_start(QUIC_CHANNEL
*ch
);
100 /* Start a locally initiated connection shutdown. */
101 void ossl_quic_channel_local_close(QUIC_CHANNEL
*ch
, uint64_t app_error_code
);
104 * Called when the handshake is confirmed.
106 int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL
*ch
);
109 * Raises a protocol error. This is intended to be the universal call suitable
110 * for handling of all peer-triggered protocol violations or errors detected by
111 * us. We specify a QUIC transport-scope error code and optional frame type
112 * which was responsible. If a frame type is not applicable, specify zero. The
113 * reason string is not currently handled, but should be a string of static
114 * storage duration. If the connection has already terminated due to a previous
115 * protocol error, this is a no-op; first error wins.
117 void ossl_quic_channel_raise_protocol_error(QUIC_CHANNEL
*ch
,
123 void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL
*ch
,
124 OSSL_QUIC_FRAME_CONN_CLOSE
*f
);
127 * Queries and Accessors
128 * =====================
131 /* Gets the reactor which can be used to tick/poll on the channel. */
132 QUIC_REACTOR
*ossl_quic_channel_get_reactor(QUIC_CHANNEL
*ch
);
134 /* Gets the QSM used with the channel. */
135 QUIC_STREAM_MAP
*ossl_quic_channel_get_qsm(QUIC_CHANNEL
*ch
);
137 /* Gets the statistics manager used with the channel. */
138 OSSL_STATM
*ossl_quic_channel_get_statm(QUIC_CHANNEL
*ch
);
141 * Gets/sets the current peer address. Generally this should be used before
142 * starting a channel in client mode.
144 int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL
*ch
, BIO_ADDR
*peer_addr
);
145 int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL
*ch
, const BIO_ADDR
*peer_addr
);
147 /* Gets/sets the underlying network read and write BIOs. */
148 BIO
*ossl_quic_channel_get_net_rbio(QUIC_CHANNEL
*ch
);
149 BIO
*ossl_quic_channel_get_net_wbio(QUIC_CHANNEL
*ch
);
150 int ossl_quic_channel_set_net_rbio(QUIC_CHANNEL
*ch
, BIO
*net_rbio
);
151 int ossl_quic_channel_set_net_wbio(QUIC_CHANNEL
*ch
, BIO
*net_wbio
);
154 * Returns an existing stream by stream ID. Returns NULL if the stream does not
157 QUIC_STREAM
*ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL
*ch
,
160 /* Returns 1 if channel is terminating or terminated. */
161 int ossl_quic_channel_is_term_any(const QUIC_CHANNEL
*ch
);
162 int ossl_quic_channel_is_terminating(const QUIC_CHANNEL
*ch
);
163 int ossl_quic_channel_is_terminated(const QUIC_CHANNEL
*ch
);
164 int ossl_quic_channel_is_active(const QUIC_CHANNEL
*ch
);
165 int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL
*ch
);