diff options
author | Benjamin Kaduk <bkaduk@akamai.com> | 2020-01-16 14:37:44 -0800 |
---|---|---|
committer | Benjamin Kaduk <kaduk@mit.edu> | 2020-03-13 15:55:49 -0700 |
commit | d3133cc77cd0b052b6792d3e1edb9e5a202c6695 (patch) | |
tree | e3cff396db046bc701388bb94e48cd5d580e38bf /doc | |
parent | 9011225188e0779833617516bdd76ab122fe2509 (diff) |
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
8876bc054802b043a3ec95554b6c5873291770be, 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)
(cherry picked from commit 06f876837a8ec76b28c42953731a156c0c3700e2)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/SSL_CTX_sess_set_get_cb.pod | 39 |
1 files changed, 21 insertions, 18 deletions
diff --git a/doc/man3/SSL_CTX_sess_set_get_cb.pod b/doc/man3/SSL_CTX_sess_set_get_cb.pod index 11eda7e141..1b0f8a341b 100644 --- a/doc/man3/SSL_CTX_sess_set_get_cb.pod +++ b/doc/man3/SSL_CTX_sess_set_get_cb.pod @@ -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 |