From: Matt Caswell <matt@openssl.org>
Date: Mon, 7 Apr 2025 09:12:55 +0000 (+0100)
Subject: Document the state of the object you get from SSL_accept_connection()
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6d8e516e0877e3bc363002b79877bce558ffbd4b;p=thirdparty%2Fopenssl.git

Document the state of the object you get from SSL_accept_connection()

The object may or may not have completed its handshake.

See also:
https://github.com/openssl/openssl/pull/27239#issuecomment-2772148408

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/27283)
---

diff --git a/doc/man3/SSL_new_listener.pod b/doc/man3/SSL_new_listener.pod
index b830bd11bd1..291c103381e 100644
--- a/doc/man3/SSL_new_listener.pod
+++ b/doc/man3/SSL_new_listener.pod
@@ -130,6 +130,14 @@ 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 new SSL object returned from SSL_accept_connection() may or may not have
+completed its handshake at the point it is returned. Optionally, you may use the
+function L<SSL_is_init_finished(3)> to determine this. You may call the
+functions L<SSL_accept(3)>, L<SSL_do_handshake(3)> or L<SSL_handle_events(3)> to
+progress the state of the SSL object towards handshake completion. Other "I/O"
+functions may also implicitly progress the state of the handshake such as
+L<SSL_poll(3)>, L<SSL_read(3)> and L<SSL_write(3)>.
+
 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.