wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update SSL_CTX_sess_set_new_cb(3) docs for refcounts

Browse source 
The existing documentation for the new-session callback was unclear
about the requirements on the callback with respect to reference-handling
of the session object being created.  Be more explicit about the
(non-)requirements on the callback code for "success" (1) and "ignore"
(0) return values.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10848)

(cherry picked from commit 188d4ec82a9b0085ac5841cce3eda95efb94f2b4)
This commit is contained in:
Benjamin Kaduk 2020-01-14 16:22:52 -08:00 committed by Ben Kaduk
parent 56c59ddd99
commit 017015ceec
1 changed files with 12 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
doc/man3/SSL_CTX_sess_set_get_cb.pod
View file

@ -54,12 +54,18 @@ session cache is realized via callback functions. Inside these callback
functions, session can be saved to disk or put into a database using the
L<d2i_SSL_SESSION(3)> interface.
The new_session_cb() is called, whenever a new session has been negotiated
and session caching is enabled (see
L<SSL_CTX_set_session_cache_mode(3)>).
The new_session_cb() is passed the B<ssl> connection and the ssl session
B<sess>. If the callback returns B<0>, the session will be immediately
removed again. Note that in TLSv1.3, sessions are established after the main
The new_session_cb() is called whenever a new session has been negotiated and
session caching is enabled (see L<SSL_CTX_set_session_cache_mode(3)>). The
new_session_cb() is passed the B<ssl> connection and the ssl session B<sess>.
Since sessions are reference-counted objects, the reference count on the
session is incremented before the callback, on behalf of the application. If
the callback returns B<0>, the session will be immediately removed from the
internal cache and the reference count released. If the callback returns B<1>,
the application retains the reference (for an entry in the
application-maintained "external session cache"), and is responsible for
calling SSL_SESSION_free() when the session reference is no longer in use.
Note that in TLSv1.3, sessions are established after the main
handshake has completed. The server decides when to send the client the session
information and this may occur some time after the end of the handshake (or not
at all). This means that applications should expect the new_session_cb()