doc: clarify SSL_SESSION ownership in PSK use session callback

kovan · t8m · commit 2b0dbbdd3664 · 2026-02-13T15:37:25.000+01:00
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 #29771) (cherry picked from commit 6d646a9)
diff --git 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
