Mirrors/openssl
0
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2026-01-18 17:11:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for OSSL_QUIC_method() and SSL_listen_ex()

Browse Source 
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/27397)
This commit is contained in:
Neil Horman
2025-10-20 11:52:44 -04:00
parent 3702f51c29
commit c2b14acee4
2 changed files with 36 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/man3/OSSL_QUIC_client_method.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_method
OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_method, OSSL_QUIC_method
- Provide SSL_METHOD objects for QUIC enabled functions
=head1 SYNOPSIS
@@ -12,6 +12,7 @@ OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, OSSL_QUIC_server_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);
const SSL_METHOD *OSSL_QUIC_method(void);
=head1 DESCRIPTION
@@ -30,13 +31,19 @@ The OSSL_QUIC_server_method() provides server-side QUIC protocol support and
must be used with the L<SSL_new_listener(3)> API. Attempting to use
OSSL_QUIC_server_method() with L<SSL_new(3)> will result in an error.
The OSSL_QUIC_method() provides generic QUIC protocol support when a user wishes to
defer selection of server or client protocol functionality until such time as a
connection is made. This is similar to the functionality provided by
L<DTLS_method(3)>, and can be used with the SSL_listen_ex() call, which behaves
similarly to L<DTLSv1_listen(3)>.
=head1 RETURN VALUES
These functions return pointers to the constant method objects.
=head1 SEE ALSO
L<SSL_CTX_new_ex(3)>, L<SSL_new_listener(3)>
L<SSL_CTX_new_ex(3)>, L<SSL_new_listener(3)>, L<SSL_listen_ex(3)>
=head1 HISTORY
@@ -45,6 +52,8 @@ OpenSSL 3.2.
OSSL_QUIC_server_method() was added in OpenSSL 3.5.
OSSL_QUIC_method() was added in OpenSSL 4.0.
=head1 COPYRIGHT
Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved.

26
doc/man3/SSL_new_listener.pod
View File

@@ -3,7 +3,7 @@
=head1 NAME
SSL_new_listener, SSL_new_listener_from, SSL_is_listener, SSL_get0_listener,
SSL_listen,
SSL_listen, SSL_listen_ex,
SSL_accept_connection, SSL_get_accept_connection_queue_len,
SSL_new_from_listener,
SSL_ACCEPT_CONNECTION_NO_BLOCK - SSL object interface for abstracted connection
@@ -20,6 +20,7 @@ acceptance
SSL *SSL_get0_listener(SSL *ssl);
int SSL_listen(SSL *ssl);
int SSL_listen_ex(SSL *ssl, SSL *new_conn);
#define SSL_ACCEPT_CONNECTION_NO_BLOCK
SSL *SSL_accept_connection(SSL *ssl, uint64_t flags);
@@ -124,6 +125,22 @@ SSL_accept_connection()) succeeds. The SSL_listen() function is idempotent,
subsequent calls on the same I<ssl> object are no-ops. This call is supported
only on listener SSL objects.
The SSL_listen_ex() function behaves in a similar fashion to L<DTLSv1_listen(3)>
in that it polls a listening SSL object, and, if a new connection is available,
writes that connection into the SSL object pointed to by B<new_conn>. Note that
once a connection is returned from a listener via this call, accepting
connections via L<SSL_accept_connection(3)> is no longer permissible, and will
result in an error. Note that many calls into the QUIC api may trigger the quic reactor
(such as L<SSL_poll(3)>), and will set the port into a mode in which L<SSL_accept_connection(3)>
is assumed. To avoid this, it is recommended that, if the use of SSL_listen_ex use is desired, that
it is the first I/O call made to the SSL object to which the port is attached.
Likewise, if a listener has accepted a connection via
L<SSL_accept_connection(3)>, it is impermissible to accept connections via
B<SSL_listen_ex()>. Note also that SSL objects passed in the B<new_conn>
parameter to B<SSL_listen_ex()> must be created using L<OSSL_QUIC_method(3)> or
L<OSSL_QUIC_server_method(3)>.
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
@@ -198,6 +215,11 @@ object on which it is called) or NULL.
SSL_listen() returns 1 on success or 0 on failure.
SSL_listen_ex() returns 1 when a new connection was accepted on the new_conn
parameter, 0 if no new connection was available at the time of the call, or -1
in the event an internal error occurred, signaling a need to check the error
queue.
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.
@@ -228,6 +250,8 @@ L<SSL_set_blocking_mode(3)>
These functions were added in OpenSSL 3.5.
SSL_listen_ex() was added in OpenSSL 4.0
=head1 COPYRIGHT
Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.