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
;
67 /* Represents the cause for a connection's termination. */
68 typedef struct quic_terminate_cause_st
{
70 * If we are in a TERMINATING or TERMINATED state, this is the error code
71 * associated with the error. This field is valid iff we are in the
72 * TERMINATING or TERMINATED states.
77 * If terminate_app is set and this is nonzero, this is the frame type which
78 * caused the connection to be terminated.
82 /* Is this error code in the transport (0) or application (1) space? */
86 * If set, the cause of the termination is a received CONNECTION_CLOSE
87 * frame. Otherwise, we decided to terminate ourselves and sent a
88 * CONNECTION_CLOSE frame (regardless of whether the peer later also sends
91 unsigned int remote
: 1;
92 } QUIC_TERMINATE_CAUSE
;
96 * Create a new QUIC channel using the given arguments. The argument structure
97 * does not need to remain allocated. Returns NULL on failure.
99 QUIC_CHANNEL
*ossl_quic_channel_new(const QUIC_CHANNEL_ARGS
*args
);
101 /* No-op if ch is NULL. */
102 void ossl_quic_channel_free(QUIC_CHANNEL
*ch
);
104 /* Set mutator callbacks for test framework support */
105 int ossl_quic_channel_set_mutator(QUIC_CHANNEL
*ch
,
106 ossl_mutate_packet_cb mutatecb
,
107 ossl_finish_mutate_cb finishmutatecb
,
111 * Connection Lifecycle Events
112 * ===========================
114 * Various events that can be raised on the channel by other parts of the QUIC
115 * implementation. Some of these are suitable for general use by any part of the
116 * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very
117 * specific use by particular components only (e.g.
118 * ossl_quic_channel_on_handshake_confirmed).
122 * To be used by a QUIC connection. Starts the channel. For a client-mode
123 * channel, this starts sending the first handshake layer message, etc. Can only
124 * be called in the idle state; successive calls are ignored.
126 int ossl_quic_channel_start(QUIC_CHANNEL
*ch
);
128 /* Start a locally initiated connection shutdown. */
129 void ossl_quic_channel_local_close(QUIC_CHANNEL
*ch
, uint64_t app_error_code
);
132 * Called when the handshake is confirmed.
134 int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL
*ch
);
137 * Raises a protocol error. This is intended to be the universal call suitable
138 * for handling of all peer-triggered protocol violations or errors detected by
139 * us. We specify a QUIC transport-scope error code and optional frame type
140 * which was responsible. If a frame type is not applicable, specify zero. The
141 * reason string is not currently handled, but should be a string of static
142 * storage duration. If the connection has already terminated due to a previous
143 * protocol error, this is a no-op; first error wins.
145 void ossl_quic_channel_raise_protocol_error(QUIC_CHANNEL
*ch
,
151 void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL
*ch
,
152 OSSL_QUIC_FRAME_CONN_CLOSE
*f
);
155 * Queries and Accessors
156 * =====================
159 /* Gets the reactor which can be used to tick/poll on the channel. */
160 QUIC_REACTOR
*ossl_quic_channel_get_reactor(QUIC_CHANNEL
*ch
);
162 /* Gets the QSM used with the channel. */
163 QUIC_STREAM_MAP
*ossl_quic_channel_get_qsm(QUIC_CHANNEL
*ch
);
165 /* Gets the statistics manager used with the channel. */
166 OSSL_STATM
*ossl_quic_channel_get_statm(QUIC_CHANNEL
*ch
);
169 * Gets/sets the current peer address. Generally this should be used before
170 * starting a channel in client mode.
172 int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL
*ch
, BIO_ADDR
*peer_addr
);
173 int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL
*ch
, const BIO_ADDR
*peer_addr
);
175 /* Gets/sets the underlying network read and write BIOs. */
176 BIO
*ossl_quic_channel_get_net_rbio(QUIC_CHANNEL
*ch
);
177 BIO
*ossl_quic_channel_get_net_wbio(QUIC_CHANNEL
*ch
);
178 int ossl_quic_channel_set_net_rbio(QUIC_CHANNEL
*ch
, BIO
*net_rbio
);
179 int ossl_quic_channel_set_net_wbio(QUIC_CHANNEL
*ch
, BIO
*net_wbio
);
182 * Returns an existing stream by stream ID. Returns NULL if the stream does not
185 QUIC_STREAM
*ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL
*ch
,
188 /* Returns 1 if channel is terminating or terminated. */
189 int ossl_quic_channel_is_term_any(const QUIC_CHANNEL
*ch
,
190 QUIC_TERMINATE_CAUSE
*cause
);
191 int ossl_quic_channel_is_terminating(const QUIC_CHANNEL
*ch
,
192 QUIC_TERMINATE_CAUSE
*cause
);
193 int ossl_quic_channel_is_terminated(const QUIC_CHANNEL
*ch
,
194 QUIC_TERMINATE_CAUSE
*cause
);
195 int ossl_quic_channel_is_active(const QUIC_CHANNEL
*ch
);
196 int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL
*ch
);
197 int ossl_quic_channel_is_handshake_confirmed(const QUIC_CHANNEL
*ch
);
199 SSL
*ossl_quic_channel_get0_ssl(QUIC_CHANNEL
*ch
);