mirror of
https://github.com/openssl/openssl.git
synced 2025-03-31 20:10:45 +08:00
QUIC: Add manpage for listener API
Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Neil Horman <nhorman@openssl.org> (Merged from https://github.com/openssl/openssl/pull/23334)
This commit is contained in:
Hugo Landau
Neil Horman
parent
745a779fb2
commit
56b59e7837
@ -2731,6 +2731,10 @@ DEPEND[html/man3/SSL_new.html]=man3/SSL_new.pod
|
||||
GENERATE[html/man3/SSL_new.html]=man3/SSL_new.pod
|
||||
DEPEND[man/man3/SSL_new.3]=man3/SSL_new.pod
|
||||
GENERATE[man/man3/SSL_new.3]=man3/SSL_new.pod
|
||||
DEPEND[html/man3/SSL_new_listener.html]=man3/SSL_new_listener.pod
|
||||
GENERATE[html/man3/SSL_new_listener.html]=man3/SSL_new_listener.pod
|
||||
DEPEND[man/man3/SSL_new_listener.3]=man3/SSL_new_listener.pod
|
||||
GENERATE[man/man3/SSL_new_listener.3]=man3/SSL_new_listener.pod
|
||||
DEPEND[html/man3/SSL_new_stream.html]=man3/SSL_new_stream.pod
|
||||
GENERATE[html/man3/SSL_new_stream.html]=man3/SSL_new_stream.pod
|
||||
DEPEND[man/man3/SSL_new_stream.3]=man3/SSL_new_stream.pod
|
||||
@ -3712,6 +3716,7 @@ html/man3/SSL_key_update.html \
|
||||
html/man3/SSL_library_init.html \
|
||||
html/man3/SSL_load_client_CA_file.html \
|
||||
html/man3/SSL_new.html \
|
||||
html/man3/SSL_new_listener.html \
|
||||
html/man3/SSL_new_stream.html \
|
||||
html/man3/SSL_pending.html \
|
||||
html/man3/SSL_poll.html \
|
||||
@ -4380,6 +4385,7 @@ man/man3/SSL_key_update.3 \
|
||||
man/man3/SSL_library_init.3 \
|
||||
man/man3/SSL_load_client_CA_file.3 \
|
||||
man/man3/SSL_new.3 \
|
||||
man/man3/SSL_new_listener.3 \
|
||||
man/man3/SSL_new_stream.3 \
|
||||
man/man3/SSL_pending.3 \
|
||||
man/man3/SSL_poll.3 \
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method
|
||||
OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_method
|
||||
- Provide SSL_METHOD objects for QUIC enabled functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
@ -11,6 +11,7 @@ OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method
|
||||
|
||||
const SSL_METHOD *OSSL_QUIC_client_method(void);
|
||||
const SSL_METHOD *OSSL_QUIC_client_thread_method(void);
|
||||
const SSL_METHOD *OSSL_QUIC_server_method(void);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
@ -25,22 +26,28 @@ The OSSL_QUIC_client_method() does not use threads and depends on
|
||||
nonblocking mode of operation and the application periodically calling SSL
|
||||
functions.
|
||||
|
||||
The OSSL_QUIC_server_method() provides server-side QUIC protocol support and
|
||||
must be used using the L<SSL_new_listener(3)> API. Attempting to use
|
||||
OSSL_QUIC_server_method() with L<SSL_new(3)> will result in an error.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
These functions return pointers to the constant method objects.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<SSL_CTX_new_ex(3)>
|
||||
L<SSL_CTX_new_ex(3)>, L<SSL_new_listener(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
OSSL_QUIC_client_method() and OSSL_QUIC_client_thread_method() were added in
|
||||
OpenSSL 3.2.
|
||||
|
||||
OSSL_QUIC_server_method() was added in OpenSSL @VERSION_QUIC_SERVER@.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
|
||||
Copyright 2022-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
|
||||
|
||||
209
doc/man3/SSL_new_listener.pod
Normal file
209
doc/man3/SSL_new_listener.pod
Normal file
@ -0,0 +1,209 @@
|
||||
=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
|
||||
|
||||
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 usage via
|
||||
L<OSSL_QUIC_server_method(3)>. 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.
|
||||
|
||||
=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
|
||||
|
||||
OSSL_QUIC_client_method() and OSSL_QUIC_client_thread_method() were added in
|
||||
OpenSSL 3.2.
|
||||
|
||||
OSSL_QUIC_server_method() was added in OpenSSL @VERSION_QUIC_SERVER@.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2022-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
|
||||
@ -2304,7 +2304,10 @@ __owur int SSL_is_connection(SSL *s);
|
||||
|
||||
__owur int SSL_is_listener(SSL *ssl);
|
||||
__owur SSL *SSL_get0_listener(SSL *s);
|
||||
#define SSL_LISTENER_FLAG_NO_ACCEPT (1UL << 0)
|
||||
__owur SSL *SSL_new_listener(SSL_CTX *ctx, uint64_t flags);
|
||||
__owur SSL *SSL_new_from_listener(SSL *ssl, uint64_t flags);
|
||||
#define SSL_ACCEPT_CONNECTION_NO_BLOCK (1UL << 0)
|
||||
__owur SSL *SSL_accept_connection(SSL *ssl, uint64_t flags);
|
||||
__owur size_t SSL_get_accept_connection_queue_len(SSL *ssl);
|
||||
__owur int SSL_listen(SSL *ssl);
|
||||
|
||||
@ -596,3 +596,4 @@ SSL_new_listener ? 3_5_0 EXIST::FUNCTION:
|
||||
SSL_accept_connection ? 3_5_0 EXIST::FUNCTION:
|
||||
SSL_get_accept_connection_queue_len ? 3_5_0 EXIST::FUNCTION:
|
||||
SSL_listen ? 3_5_0 EXIST::FUNCTION:
|
||||
SSL_new_from_listener ? 3_5_0 EXIST::FUNCTION:
|
||||
|
||||
@ -753,6 +753,7 @@ SSL_STREAM_STATE_FINISHED define
|
||||
SSL_STREAM_STATE_RESET_LOCAL define
|
||||
SSL_STREAM_STATE_RESET_REMOTE define
|
||||
SSL_STREAM_STATE_CONN_CLOSED define
|
||||
SSL_ACCEPT_CONNECTION_NO_BLOCK define
|
||||
SSL_ACCEPT_STREAM_NO_BLOCK define
|
||||
SSL_DEFAULT_STREAM_MODE_AUTO_BIDI define
|
||||
SSL_DEFAULT_STREAM_MODE_AUTO_UNI define
|
||||
@ -777,6 +778,8 @@ SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT define
|
||||
SSL_VALUE_STREAM_WRITE_BUF_SIZE define
|
||||
SSL_VALUE_STREAM_WRITE_BUF_USED define
|
||||
SSL_VALUE_STREAM_WRITE_BUF_AVAIL define
|
||||
SSL_WRITE_FLAG_CONCLUDE define
|
||||
SSL_LISTENER_FLAG_NO_ACCEPT define
|
||||
TLS_DEFAULT_CIPHERSUITES define deprecated 3.0.0
|
||||
X509_CRL_http_nbio define deprecated 3.0.0
|
||||
X509_http_nbio define deprecated 3.0.0
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user