Commit 6d646a94af for openssl.org

commit 6d646a94af5d604cabff9005bd6bf8475a635b75
Author: kovan <xaum.io@gmail.com>
Date:   Tue Feb 3 10:32:56 2026 +0100

    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 dd302983fd..48d1bef4a3 100644
--- 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