1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
=pod
=head1 NAME
SSL_new_listener, SSL_is_listener, SSL_get0_listener, SSL_listen,
SSL_accept_connection, SSL_get_accept_connection_queue_len,
SSL_new_from_listener, SSL_LISTENER_FLAG_NO_ACCEPT,
SSL_ACCEPT_CONNECTION_NO_BLOCK - SSL object interface for abstracted connection
acceptance
=head1 SYNOPSIS
#include <openssl/ssl.h>
#define SSL_LISTENER_FLAG_NO_ACCEPT
SSL *SSL_new_listener(SSL_CTX *ctx, uint64_t flags);
int SSL_is_listener(SSL *ssl);
SSL *SSL_get0_listener(SSL *ssl);
int SSL_listen(SSL *ssl);
#define SSL_ACCEPT_CONNECTION_NO_BLOCK
SSL *SSL_accept_connection(SSL *ssl, uint64_t flags);
size_t SSL_get_accept_connection_queue_len(SSL *ssl);
SSL *SSL_new_from_listener(SSL *ssl, uint64_t flags);
=head1 DESCRIPTION
The SSL_new_listener() function creates a listener SSL object. A listener SSL
object differs from an ordinary SSL object in that it is used to provide an
abstraction for the acceptance of network connections in a protocol-agnostic
manner. It cannot be used, for example, for sending or receiving data using
L<SSL_write_ex(3)> or L<SSL_read_ex(3)>. In general, only those functions
expressly documented as being supported on a listener SSL object are available.
A listener SSL object supports the following operations:
=over 4
=item
Standard reference counting and free operations, such as L<SSL_up_ref(3)> and
L<SSL_free(3)>;
=item
Network BIO configuration operations, such as L<SSL_set_bio(3)>;
=item
Event processing and polling enablement APIs such as L<SSL_handle_events(3)>,
L<SSL_get_event_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
L<SSL_get_wpoll_descriptor(3)>, L<SSL_net_read_desired(3)> and
L<SSL_net_write_desired(3)>;
=item
Certain configurable parameters described in L<SSL_get_value_uint(3)> (see
L<SSL_get_value_uint(3)> for details);
=item
Accepting network connections using the functions documented in this manual
page, such as SSL_accept_connection().
=back
The basic workflow of using a listener object is as follows:
=over 4
=item
Create a new listener object using SSL_new_listener() using a B<SSL_CTX> which
uses a supported B<SSL_METHOD> (such as L<OSSL_QUIC_server_method(3)>);
=item
Configure appropriate network BIOs using L<SSL_set_bio(3)> on the listener SSL
object;
=item
Configure the blocking mode using L<SSL_set_blocking_mode(3)>;
=item
Accept connections in a loop by calling SSL_accept_connection(). Each returned
SSL object is a valid connection which can be used in a normal manner.
=back
The SSL_is_listener() function returns 1 if and only if a SSL object is a
listener SSL object.
The SSL_get0_listener() function returns a listener object which is related to
the given SSL object, if there is one. For a listener object, this is the same
object (the function returns itself). For a connection object which was created
by a listener object, that listener object is returned. An SSL object which is
not a listener object and which is not descended from a listener object (e.g. a
connection obtained using SSL_accept_connection()) or indirectly from a listener
object (e.g. a QUIC stream SSL object obtained using SSL_accept_stream() called
on a connection obtained using SSL_accept_connection()) returns NULL.
The SSL_listen() function begins listening after a listener has been created.
Appropriate BIOs must have been configured before calling SSL_listen(), along
with any other needed configuration for the listener SSL object. It is
ordinarily not needed to call SSL_listen() because it will be called
automatically on the first call to SSL_accept_connection(). However,
SSL_listen() may be called explicitly if it is desired to control precisely when
the listening process begins, or to ensure that no errors occur when starting to
listen for connections. After a call to SSL_listen() (or
SSL_accept_connection()) succeeds, subsequent calls to SSL_listen() are
idempotent no-ops. This call is supported only on a listener SSL object.
The SSL_accept_connection() call is supported only on a listener SSL object and
accepts a new incoming connection. A new SSL object representing the accepted
connection is created and returned on success. If no incoming connection is
available and the listener SSL object is configured in nonblocking mode, NULL is
returned.
The B<SSL_ACCEPT_CONNECTION_NO_BLOCK> flag may be specified to
SSL_accept_connection(). If specified, the call does not block even if the
listener SSL object is configured in blocking mode.
The SSL_get_accept_connection_queue_len() call returns an informational value
listing the number of connections waiting to be popped from the queue via calls
to SSL_accept_connection(). Note that since this may change between subsequent
API calls to the listener SSL object, it should be used for informational
purposes only.
Currently, listener SSL objects are only supported for QUIC server usage via
L<OSSL_QUIC_server_method(3)>, or QUIC client-only usage via
L<OSSL_QUIC_client_method(3)> or L<OSSL_QUIC_client_thread_method(3)> (see
L</CLIENT-ONLY USAGE>). It is expected that the listener interface, which
provides an abstracted API for connection acceptance, will be expanded to
support other protocols, such as TLS over TCP, plain TCP or DTLS in future.
SSL_listen() and SSL_accept_connection() are "I/O" functions, meaning that they
update the value returned by L<SSL_get_error(3)> if they fail.
=head1 CLIENT-ONLY USAGE
It is also possible to use the listener interface without accepting any
connections and without listening for connections. This can be useful in
circumstances where it is desirable for multiple connections to share the same
underlying network resources. For example, multiple outgoing QUIC client
connections could be made to use the same underlying UDP socket.
To use client-only mode, pass the flag B<SSL_LISTENER_FLAG_NO_ACCEPT> when
calling SSL_new_listener(). In this mode, SSL_listen() still begins the process
of handling network resources, but incoming connections are never accepted.
Calling SSL_accept_connection() is an error and will return NULL. One or more
outgoing connections under a listener can then be created using the call
SSL_new_from_listener().
The SSL_new_from_listener() creates a client connection under a given listener
SSL object. For QUIC, it is also possible to use SSL_new_from_listener() in
conjunction with a listener which does accept incoming connections (i.e., which
was not created using B<SSL_LISTENER_FLAG_NO_ACCEPT>), leading to a UDP network
endpoint which has both incoming and outgoing connections.
The I<flags> argument of SSL_new_from_listener() is reserved and must be set to
0.
Creating a listener using a B<SSL_CTX> which uses a client-oriented
B<SSL_METHOD> such as L<OSSL_QUIC_client_method(3)> or
L<OSSL_QUIC_client_thread_method(3)> automatically implies the
B<SSL_LISTENER_FLAG_NO_ACCEPT> flag. The B<SSL_LISTENER_FLAG_NO_ACCEPT> flag may
optionally also be specified in this case but is ignored. This is an alternative
way of using the listener functionality in client-only mode.
=head1 RETURN VALUES
SSL_new_listener() returns a new listener SSL object or NULL on failure.
SSL_is_listener() returns 0 or 1 depending on the type of the SSL object on
which it is called.
SSL_get0_listener() returns an SSL object pointer (potentially to the same
object on which it is called) or NULL.
SSL_listen() returns 1 on success or 0 on failure.
SSL_accept_connection() returns a pointer to a new SSL object on success or NULL
on failure. On success, the caller assumes ownership of the reference.
SSL_get_accept_connection_queue_len() returns a nonnegative value, or 0 if
called on an unsupported SSL object type.
SSL_new_from_listener() returns a pointer to a new SSL object on success or NULL
on failure. On success, the caller assumes ownership of the reference.
=head1 SEE ALSO
L<OSSL_QUIC_server_method(3)>, L<SSL_free(3)>, L<SSL_set_bio(3)>,
L<SSL_handle_events(3)>, L<SSL_get_rpoll_descriptor(3)>,
L<SSL_set_blocking_mode(3)>
=head1 HISTORY
These functions were added in OpenSSL @VERSION_QUIC_SERVER@.
=head1 COPYRIGHT
Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
|
