From cc857d358ba81616fdee4e811cd0915d37e0a1b4 Mon Sep 17 00:00:00 2001
From: Matt Caswell <matt@openssl.org>
Date: Mon, 7 Apr 2025 10:12:55 +0100
Subject: [PATCH] Document the state of the object you get from
 SSL_accept_connection()
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

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)

(cherry picked from commit 6d8e516e0877e3bc363002b79877bce558ffbd4b)
---
 doc/man3/SSL_new_listener.pod | 8 ++++++++
 1 file changed, 8 insertions(+)

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.
-- 
2.47.2