doc: clarify SSL_SESSION ownership in PSK use session callback

Document that when the psk_use_session callback is invoked multiple times
and wishes to return the same SSL_SESSION pointer, it must call
SSL_SESSION_up_ref() first since ownership is transferred on each call.
This prevents use-after-free errors from incorrect callback implementations.

Fixes #28267

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
MergeDate: Fri Feb 13 14:36:50 2026
(Merged from https://github.com/openssl/openssl/pull/29771)

diff --git a/doc/man3/SSL_CTX_set_psk_client_callback.pod b/doc/man3/SSL_CTX_set_psk_client_callback.pod
index dd302983fddebfc54874f24db0be765f116f86ad..48d1bef4a39a26fdf6a0c7e9c044d3653dbfd4af 100644 (file)
--- a/doc/man3/SSL_CTX_set_psk_client_callback.pod
+++ b/doc/man3/SSL_CTX_set_psk_client_callback.pod
@@ -93,6 +93,14 @@ be used as the basis for a PSK.
 Ownership of the SSL_SESSION object is passed to the OpenSSL library and so it
 should not be freed by the application.
 
+Note that as described above, the callback may be called a second time during a
+handshake. Since ownership of the SSL_SESSION is transferred to OpenSSL on each
+call, if the callback wishes to return the same SSL_SESSION pointer on a
+subsequent invocation, it must first call L<SSL_SESSION_up_ref(3)> to increment
+the reference count. Failure to do so will result in a use-after-free error.
+Alternatively, the callback may return a different SSL_SESSION object on each
+call (e.g., by calling L<SSL_SESSION_dup(3)>).
+
 It is also possible for the callback to succeed but not supply a PSK. In this
 case no PSK will be sent to the server but the handshake will continue. To do
 this the callback should return successfully and ensure that B<*sess> is