]>
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 | ||
20 | /* | |
21 | * QUIC Channel | |
22 | * ============ | |
23 | * | |
24 | * A QUIC channel (QUIC_CHANNEL) is an object which binds together all of the | |
25 | * various pieces of QUIC into a single top-level object, and handles connection | |
26 | * state which is not specific to the client or server roles. In particular, it | |
27 | * is strictly separated from the libssl front end I/O API personality layer, | |
28 | * and is not an SSL object. | |
29 | * | |
30 | * The name QUIC_CHANNEL is chosen because QUIC_CONNECTION is already in use, | |
31 | * but functionally these relate to the same thing (a QUIC connection). The use | |
32 | * of two separate objects ensures clean separation between the API personality | |
33 | * layer and common code for handling connections, and between the functionality | |
34 | * which is specific to clients and which is specific to servers, and the | |
35 | * functionality which is common to both. | |
36 | * | |
37 | * The API personality layer provides SSL objects (e.g. a QUIC_CONNECTION) which | |
38 | * consume a QUIC channel and implement a specific public API. Things which are | |
39 | * handled by the API personality layer include emulation of blocking semantics, | |
40 | * handling of SSL object mode flags like non-partial write mode, etc. | |
41 | * | |
42 | * Where the QUIC_CHANNEL is used in a server role, there is one QUIC_CHANNEL | |
43 | * per connection. In the future a QUIC Channel Manager will probably be defined | |
44 | * to handle ownership of resources which are shared between connections (e.g. | |
45 | * demuxers). Since we only use server-side functionality for dummy test servers | |
46 | * for now, which only need to handle one connection at a time, this is not | |
47 | * currently modelled. | |
48 | */ | |
49 | ||
50 | #define QUIC_CHANNEL_STATE_IDLE 0 | |
51 | #define QUIC_CHANNEL_STATE_ACTIVE 1 | |
52 | #define QUIC_CHANNEL_STATE_TERMINATING_CLOSING 2 | |
53 | #define QUIC_CHANNEL_STATE_TERMINATING_DRAINING 3 | |
54 | #define QUIC_CHANNEL_STATE_TERMINATED 4 | |
55 | ||
56 | typedef struct quic_channel_args_st { | |
57 | OSSL_LIB_CTX *libctx; | |
58 | const char *propq; | |
59 | int is_server; | |
60 | } QUIC_CHANNEL_ARGS; | |
61 | ||
62 | typedef struct quic_channel_st QUIC_CHANNEL; | |
63 | ||
64 | /* | |
65 | * Create a new QUIC channel using the given arguments. The argument structure | |
66 | * does not need to remain allocated. Returns NULL on failure. | |
67 | */ | |
68 | QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args); | |
69 | ||
70 | /* No-op if ch is NULL. */ | |
71 | void ossl_quic_channel_free(QUIC_CHANNEL *ch); | |
72 | ||
73 | /* | |
74 | * Connection Lifecycle Events | |
75 | * =========================== | |
76 | * | |
77 | * Various events that can be raised on the channel by other parts of the QUIC | |
78 | * implementation. Some of these are suitable for general use by any part of the | |
79 | * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very | |
80 | * specific use by particular components only (e.g. | |
81 | * ossl_quic_channel_on_handshake_confirmed). | |
82 | * | |
83 | */ | |
84 | ||
85 | /* | |
86 | * To be used by a QUIC connection. Starts the channel. For a client-mode | |
87 | * channel, this starts sending the first handshake layer message, etc. Can only | |
88 | * be called in the idle state; successive calls are ignored. | |
89 | */ | |
90 | int ossl_quic_channel_start(QUIC_CHANNEL *ch); | |
91 | ||
92 | /* Start a locally initiated connection shutdown. */ | |
93 | void ossl_quic_channel_local_close(QUIC_CHANNEL *ch); | |
94 | ||
95 | /* | |
96 | * Called when the handshake is confirmed. | |
97 | */ | |
98 | int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch); | |
99 | ||
100 | /* | |
101 | * Raises a protocol error. This is intended to be the universal call suitable | |
102 | * for handling of all peer-triggered protocol violations or errors detected by | |
103 | * us. We specify a QUIC transport-scope error code and optional frame type | |
104 | * which was responsible. If a frame type is not applicable, specify zero. The | |
105 | * reason string is not currently handled, but should be a string of static | |
106 | * storage duration. If the connection has already terminated due to a previous | |
107 | * protocol error, this is a no-op; first error wins. | |
108 | */ | |
109 | void ossl_quic_channel_raise_protocol_error(QUIC_CHANNEL *ch, | |
110 | uint64_t error_code, | |
111 | uint64_t frame_type, | |
112 | const char *reason); | |
113 | ||
114 | /* For RXDP use. */ | |
115 | void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch, | |
116 | OSSL_QUIC_FRAME_CONN_CLOSE *f); | |
117 | ||
118 | /* | |
119 | * Queries and Accessors | |
120 | * ===================== | |
121 | */ | |
122 | ||
123 | /* Gets the reactor which can be used to tick/poll on the channel. */ | |
124 | QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch); | |
125 | ||
126 | /* Gets the QSM used with the channel. */ | |
127 | QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch); | |
128 | ||
129 | /* Gets the statistics manager used with the channel. */ | |
130 | OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch); | |
131 | ||
132 | /* | |
133 | * Gets/sets the current peer address. Generally this should be used before | |
134 | * starting a channel in client mode. | |
135 | */ | |
136 | int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr); | |
137 | int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr); | |
138 | ||
139 | /* Gets/sets the underlying network read and write BIOs. */ | |
140 | BIO *ossl_quic_channel_get_net_rbio(QUIC_CHANNEL *ch); | |
141 | BIO *ossl_quic_channel_get_net_wbio(QUIC_CHANNEL *ch); | |
142 | int ossl_quic_channel_set0_net_rbio(QUIC_CHANNEL *ch, BIO *net_rbio); | |
143 | int ossl_quic_channel_set0_net_wbio(QUIC_CHANNEL *ch, BIO *net_wbio); | |
144 | ||
145 | /* | |
146 | * Returns an existing stream by stream ID. Returns NULL if the stream does not | |
147 | * exist. | |
148 | */ | |
149 | QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch, | |
150 | uint64_t stream_id); | |
151 | ||
152 | /* Returns 1 if channel is terminating or terminated. */ | |
153 | int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch); | |
154 | int ossl_quic_channel_is_terminating(const QUIC_CHANNEL *ch); | |
155 | int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch); | |
156 | int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch); | |
157 | int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch); | |
158 | ||
159 | #endif |