Commit dbc66697a3 for openssl.org
commit dbc66697a36a2c2b6c025c2fd6998a40f0882f9a
Author: Ryan Hooper <ryanh@openssl.foundation>
Date: Mon Aug 17 10:18:58 2026 -0400
DTLS 1.3 Set the listener demo to non-blocking mode
A DTLS listener, and the connections it accepts, now default to
blocking mode. The dtlslistenerecho demo drives the listener and its
connections with SSL_poll() and uses SSL_ACCEPT_CONNECTION_NO_BLOCK,
so call SSL_set_blocking_mode() on the listener to put it back into
non-blocking mode. The accepted connections inherit that mode.
Also update the DTLS 1.3 guide (ossl-guide-dtlsv13) to mention
SSL_set_blocking_mode() and SSL_get_blocking_mode() for DTLS
listeners and to note that a listener is blocking by default.
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
Reviewed-by: Jakub Zelenka <jakub.zelenka@openssl.foundation>
Reviewed-by: Matt Caswell <matt@openssl.foundation>
Merge-date: Thu Aug 20 09:50:38 2026
Merged-from: https://github.com/openssl/openssl/pull/31983
diff --git a/demos/dtlslistenerecho/README.md b/demos/dtlslistenerecho/README.md
index d13a2afc24..7811e9341f 100644
--- a/demos/dtlslistenerecho/README.md
+++ b/demos/dtlslistenerecho/README.md
@@ -40,6 +40,9 @@ The code demonstrates
---------------------
- DTLS Server using SSL Listener APIs to establish Connections
+- Placing the listener (and the connections it accepts, which inherit its mode)
+ into non-blocking mode via SSL_set_blocking_mode(), since a DTLS listener is
+ blocking by default
- DTLS Server validating Clients via HRR/HVR
- Thread-per-connection model for handling multiple clients
- Clients sending data to an established Server
diff --git a/demos/dtlslistenerecho/main.c b/demos/dtlslistenerecho/main.c
index 53e117b371..7d8f9ff310 100644
--- a/demos/dtlslistenerecho/main.c
+++ b/demos/dtlslistenerecho/main.c
@@ -184,6 +184,19 @@ static int create_dtls_listener(SSL_CTX *ssl_ctx, int port,
SSL_set0_wbio(*listener, listener_bio);
listener_bio = NULL; /* Both references transferred to listener */
+ /*
+ * A DTLS listener is blocking by default, and the connections it returns
+ * inherit that mode. This demo drives the listener and its connections with
+ * SSL_poll() and passes SSL_ACCEPT_CONNECTION_NO_BLOCK to
+ * SSL_accept_connection(), so put the listener into non-blocking mode. The
+ * accepted connections then inherit non-blocking mode as well.
+ */
+ if (SSL_set_blocking_mode(*listener, 0) != 1) {
+ fprintf(stderr, "Unable to set listener to non-blocking mode\n");
+ ERR_print_errors_fp(stderr);
+ goto err;
+ }
+
/* Start listening for incoming connections */
if (SSL_listen(*listener) != 1) {
fprintf(stderr, "SSL_listen failed\n");
diff --git a/doc/man7/ossl-guide-dtlsv13.pod b/doc/man7/ossl-guide-dtlsv13.pod
index b565337b42..fc72ceb090 100644
--- a/doc/man7/ossl-guide-dtlsv13.pod
+++ b/doc/man7/ossl-guide-dtlsv13.pod
@@ -175,6 +175,26 @@ connections. Each accepted connection has completed cookie validation (if requir
but still requires L<SSL_do_handshake(3)> or L<SSL_accept(3)> to complete the TLS
handshake before application data can be exchanged.
+By default a DTLS listener created with L<SSL_new_listener(3)> operates in
+blocking mode. Because a listener demultiplexes a single UDP socket across many
+connections, it cannot allow a read for one connection to block and thereby
+stall the others. Its network BIO is therefore configured for nonblocking
+operation, and blocking is instead provided by waiting for readiness of the
+underlying socket. This applies to L<SSL_accept_connection(3)> on the listener
+as well as to L<SSL_read(3)> and L<SSL_write(3)> on the connections it returns.
+
+Use L<SSL_set_blocking_mode(3)> to enable or disable blocking mode, and
+L<SSL_get_blocking_mode(3)> to query it. The blocking mode of a listener is
+normally configured once, before it is used.
+
+A connection SSL object returned by L<SSL_accept_connection(3)> inherits the
+blocking mode of the listener it came from. Calling L<SSL_set_blocking_mode(3)>
+on such a connection overrides that inheritance for that connection only. To
+perform a single nonblocking accept on an otherwise blocking listener, pass the
+B<SSL_ACCEPT_CONNECTION_NO_BLOCK> flag to L<SSL_accept_connection(3)>.
+
+See L<SSL_set_blocking_mode(3)> for full details.
+
The following tunables are available via L<SSL_get_value_uint(3)> /
L<SSL_set_value_uint(3)>: B<SSL_VALUE_DTLS_LISTENER_MAX_PENDING_CONNS>
(pending-connection cap, default 256), B<SSL_VALUE_DTLS_LISTENER_PENDING_TIMEOUT>
@@ -265,7 +285,8 @@ L<https://github.com/openssl/openssl/blob/master/demos/dtlslistenerecho/main.c>.
=head1 SEE ALSO
L<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>,
-L<ossl-guide-libssl-introduction(7)>, L<ossl-guide-tls-introduction(7)>
+L<ossl-guide-libssl-introduction(7)>, L<ossl-guide-tls-introduction(7)>,
+L<SSL_set_blocking_mode(3)>, L<SSL_new_listener(3)>, L<SSL_accept_connection(3)>
=head1 COPYRIGHT