SSL_set_blocking_mode¶

NAME¶

SSL_set_blocking_mode, SSL_get_blocking_mode - configure blocking mode for a QUIC or DTLS listener SSL object

SYNOPSIS¶

#include <openssl/ssl.h>

int SSL_set_blocking_mode(SSL *s, int blocking);
int SSL_get_blocking_mode(SSL *s);

DESCRIPTION¶

SSL_set_blocking_mode() can be used to enable or disable blocking mode on an SSL object which has a blocking mode of its own. For QUIC that means a connection, stream or listener SSL object. For DTLS it means a listener SSL object created with SSL_new_listener(3), or a connection SSL object returned from one by SSL_accept_connection(3). By default, blocking is enabled, unless the SSL object is configured to use an underlying read or write BIO which cannot provide a poll descriptor (see BIO_get_rpoll_descriptor(3)), as blocking mode cannot be supported in this case.

To enable blocking mode, call SSL_set_blocking_mode() with blocking set to 1; to disable it, call SSL_set_blocking_mode() with blocking set to 0.

To retrieve the current blocking mode, call SSL_get_blocking_mode().

Blocking mode means that calls such as SSL_read() and SSL_write() will block until the requested operation can be performed. In nonblocking mode, these calls will fail if the requested operation cannot be performed immediately; see SSL_get_error(3).

Other kinds of SSL object, such as those for TLS or a DTLS object which did not come from a listener, automatically function in blocking or nonblocking mode based on whether the underlying network read and write BIOs provided to the SSL object are themselves configured in nonblocking mode, and so have no separate blocking mode to configure.

QUIC connections¶

Where a QUIC connection SSL object is used in nonblocking mode, an application is responsible for ensuring that the SSL object is ticked regularly; see SSL_handle_events(3).

Blocking mode is disabled automatically if the application provides a QUIC connection SSL object with a network BIO which cannot support blocking mode. To re-enable blocking mode in this case, an application must set a network BIO which can support blocking mode and explicitly call SSL_set_blocking_mode().

DTLS listeners¶

A DTLS listener demultiplexes a single network socket to many connections, so it cannot allow a read for one connection to block and thereby stall the others. Its network BIO is therefore configured for nonblocking operation when it is set, and blocking mode is provided by waiting for readiness of that socket instead, as it is for QUIC. This applies to SSL_accept_connection(3) on the listener as well as to reads and writes on the connections it returns. A write which the socket cannot accept is retried once it can be sent, where a nonblocking connection discards the datagram and reports that the write should be retried.

A connection SSL object returned by SSL_accept_connection(3) inherits the blocking mode of the listener it came from. Calling SSL_set_blocking_mode() on such a connection overrides that inheritance for that connection only, and there is no way to return it to inheriting afterwards. The blocking mode of a listener is normally configured once, before it is used.

A DTLS listener whose network BIO cannot provide a poll descriptor, such as one using a memory BIO, has nothing to wait on and is therefore nonblocking whatever has been requested.

RETURN VALUES¶

SSL_set_blocking_mode() returns 1 on success and 0 on failure. The function fails if called on an SSL object which has no blocking mode of its own, or if blocking mode was requested and cannot be used for the given object.

SSL_get_blocking_mode() returns 1 if blocking is currently enabled and 0 if it is not. It returns -1 if called on an SSL object which has no blocking mode of its own.

HISTORY¶

The SSL_set_blocking_mode() and SSL_get_blocking_mode() functions were added in OpenSSL 3.2. Support for DTLS listeners and the connections created from them was added in OpenSSL 4.1.

COPYRIGHT¶

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 https://www.openssl.org/source/license.html.