]>
Commit | Line | Data |
---|---|---|
f538b421 HL |
1 | /* |
2 | * Copyright 2022 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 | ||
10 | #ifndef OSSL_QUIC_CHANNEL_H | |
11 | # define OSSL_QUIC_CHANNEL_H | |
12 | ||
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" | |
19 | ||
6292519c HL |
20 | # ifndef OPENSSL_NO_QUIC |
21 | ||
f538b421 HL |
22 | /* |
23 | * QUIC Channel | |
24 | * ============ | |
25 | * | |
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. | |
31 | * | |
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. | |
38 | * | |
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. | |
43 | * | |
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 | |
49 | * currently modelled. | |
50 | */ | |
51 | ||
6292519c HL |
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 | |
f538b421 HL |
57 | |
58 | typedef struct quic_channel_args_st { | |
59 | OSSL_LIB_CTX *libctx; | |
60 | const char *propq; | |
61 | int is_server; | |
2723d705 | 62 | SSL *tls; |
f538b421 HL |
63 | } QUIC_CHANNEL_ARGS; |
64 | ||
65 | typedef struct quic_channel_st QUIC_CHANNEL; | |
66 | ||
67 | /* | |
68 | * Create a new QUIC channel using the given arguments. The argument structure | |
69 | * does not need to remain allocated. Returns NULL on failure. | |
70 | */ | |
71 | QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args); | |
72 | ||
73 | /* No-op if ch is NULL. */ | |
74 | void ossl_quic_channel_free(QUIC_CHANNEL *ch); | |
75 | ||
14e31409 MC |
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, | |
80 | void *mutatearg); | |
81 | ||
f538b421 HL |
82 | /* |
83 | * Connection Lifecycle Events | |
84 | * =========================== | |
85 | * | |
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). | |
f538b421 HL |
91 | */ |
92 | ||
93 | /* | |
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. | |
97 | */ | |
98 | int ossl_quic_channel_start(QUIC_CHANNEL *ch); | |
99 | ||
100 | /* Start a locally initiated connection shutdown. */ | |
e8043229 | 101 | void ossl_quic_channel_local_close(QUIC_CHANNEL *ch, uint64_t app_error_code); |
f538b421 HL |
102 | |
103 | /* | |
104 | * Called when the handshake is confirmed. | |
105 | */ | |
106 | int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch); | |
107 | ||
108 | /* | |
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. | |
116 | */ | |
117 | void ossl_quic_channel_raise_protocol_error(QUIC_CHANNEL *ch, | |
118 | uint64_t error_code, | |
119 | uint64_t frame_type, | |
120 | const char *reason); | |
121 | ||
122 | /* For RXDP use. */ | |
123 | void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch, | |
124 | OSSL_QUIC_FRAME_CONN_CLOSE *f); | |
125 | ||
126 | /* | |
127 | * Queries and Accessors | |
128 | * ===================== | |
129 | */ | |
130 | ||
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); | |
133 | ||
134 | /* Gets the QSM used with the channel. */ | |
135 | QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch); | |
136 | ||
137 | /* Gets the statistics manager used with the channel. */ | |
138 | OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch); | |
139 | ||
140 | /* | |
141 | * Gets/sets the current peer address. Generally this should be used before | |
142 | * starting a channel in client mode. | |
143 | */ | |
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); | |
146 | ||
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); | |
d1ac77b1 HL |
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); | |
f538b421 HL |
152 | |
153 | /* | |
154 | * Returns an existing stream by stream ID. Returns NULL if the stream does not | |
155 | * exist. | |
156 | */ | |
157 | QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch, | |
158 | uint64_t stream_id); | |
159 | ||
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); | |
166 | ||
6292519c HL |
167 | # endif |
168 | ||
f538b421 | 169 | #endif |