mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-30 14:01:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

Additional updates to SSL_CTX_sess_set_get_cb.pod

Browse Source 
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 =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. called whenever a new session was negotiated.
SSL_CTX_sess_set_remove_cb() sets the callback function, which is SSL_CTX_sess_set_remove_cb() sets the callback function that is
automatically called whenever a session is removed by the SSL engine, called whenever a session is removed by the SSL engine. For example,
because it is considered faulty or the session has become obsolete because this can occur because a session is considered faulty or has become obsolete
of exceeding the timeout value. because of exceeding the timeout value.
SSL_CTX_sess_set_get_cb() sets the callback function which is called, SSL_CTX_sess_set_get_cb() sets the callback function that is called
whenever a SSL/TLS client proposed to resume a session but the session whenever a TLS client proposed to resume a session but the session
could not be found in the internal session cache (see could not be found in the internal session cache (see
L<SSL_CTX_set_session_cache_mode(3)>). 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_new_cb(), SSL_CTX_sess_get_remove_cb(), and
SSL_CTX_sess_get_get_cb() retrieve the function pointers set by the 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 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 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 Since sessions are reference-counted objects, the reference count on the
session is incremented before the callback, on behalf of the application. If 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 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 resumption once. One way of enforcing that is for applications to call
L<SSL_CTX_remove_session(3)> after a session has been used. 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 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 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 it is expired or when a connection was not shutdown cleanly. It also happens
for all sessions in the internal session cache when for all sessions in the internal session cache when
L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed 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 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 The get_session_cb() is only called on SSL/TLS servers, and is given
proposed by the client. The get_session_cb() is always called, also when 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 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<ssl> connection and the session id of length B<length> at the memory location
B<data>. With the parameter B<copy> the callback can require the 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, SSL engine to increment the reference count of the SSL_SESSION object;
Normally the reference count is not incremented and therefore the setting B<copy> to B<0> causes the reference count to remain unchanged.
session must not be explicitly freed with 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)>. L<SSL_SESSION_free(3)>.
=head1 RETURN VALUES =head1 RETURN VALUES