root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity

Additional updates to SSL_CTX_sess_set_get_cb.pod 

Generally modernize the language.

Refer to TLS instead of SSL/TLS, and try to have more consistent
usage of commas and that/which.

Reword some descriptions to avoid implying that a list of potential
reasons for behavior is an exhaustive list.

Clarify how get_session_cb() is only called on servers (i.e., in general,
and that it's given the session ID proposed by the client).

Clarify the semantics of the get_cb()'s "copy" argument.
The behavior seems to have changed in commit
8876bc0548, though the behavior prior
to that commit was not to leave the reference-count unchanged if
*copy was not written to -- instead, libssl seemed to assume that the
callback already had incremented the reference count.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10943)
This commit is contained in:
Benjamin Kaduk 2020-01-16 14:37:44 -08:00 committed by Benjamin Kaduk
parent c08dea30d4
commit 06f876837a
1 changed files with 21 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
doc/man3/SSL_CTX_sess_set_get_cb.pod
View File

@ -28,19 +28,19 @@ SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SS
=head1 DESCRIPTION
SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
SSL_CTX_sess_set_new_cb() sets the callback function that is
called whenever a new session was negotiated.
SSL_CTX_sess_set_remove_cb() sets the callback function, which is
automatically called whenever a session is removed by the SSL engine,
because it is considered faulty or the session has become obsolete because
of exceeding the timeout value.
SSL_CTX_sess_set_remove_cb() sets the callback function that is
called whenever a session is removed by the SSL engine. For example,
this can occur because a session is considered faulty or has become obsolete
because of exceeding the timeout value.
SSL_CTX_sess_set_get_cb() sets the callback function which is called,
whenever a SSL/TLS client proposed to resume a session but the session
SSL_CTX_sess_set_get_cb() sets the callback function that is called
whenever a TLS client proposed to resume a session but the session
could not be found in the internal session cache (see
L<SSL_CTX_set_session_cache_mode(3)>).
(SSL/TLS server only.)
(TLS server only.)
SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
SSL_CTX_sess_get_get_cb() retrieve the function pointers set by the
@ -56,7 +56,8 @@ 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>.
new_session_cb() is passed the B<ssl> connection and the nascent
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
@ -78,21 +79,23 @@ In TLSv1.3 it is recommended that each SSL_SESSION object is only used for
resumption once. One way of enforcing that is for applications to call
L<SSL_CTX_remove_session(3)> after a session has been used.
The remove_session_cb() is called, whenever the SSL engine removes a session
from the internal cache. This happens when the session is removed because
The remove_session_cb() is called whenever the SSL engine removes a session
from the internal cache. This can happen when the session is removed because
it is expired or when a connection was not shutdown cleanly. It also happens
for all sessions in the internal session cache when
L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed
the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
The get_session_cb() is only called on SSL/TLS servers with the session id
proposed by the client. The get_session_cb() is always called, also when
The get_session_cb() is only called on SSL/TLS servers, and is given
the session id
proposed by the client. The get_session_cb() is always called, even when
session caching was disabled. The get_session_cb() is passed the
B<ssl> connection, the session id of length B<length> at the memory location
B<data>. With the parameter B<copy> the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object,
Normally the reference count is not incremented and therefore the
session must not be explicitly freed with
B<ssl> connection and the session id of length B<length> at the memory location
B<data>. By setting the parameter B<copy> to B<1>, the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object;
setting B<copy> to B<0> causes the reference count to remain unchanged.
If the get_session_cb() does not write to B<copy>, the reference count
is incremented and the session must be explicitly freed with
L<SSL_SESSION_free(3)>.
=head1 RETURN VALUES