From d3133cc77cd0b052b6792d3e1edb9e5a202c6695 Mon Sep 17 00:00:00 2001 From: Benjamin Kaduk Date: Thu, 16 Jan 2020 14:37:44 -0800 Subject: [PATCH] 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 (Merged from https://github.com/openssl/openssl/pull/10943) (cherry picked from commit 06f876837a8ec76b28c42953731a156c0c3700e2) --- doc/man3/SSL_CTX_sess_set_get_cb.pod | 39 +++++++++++++++------------- 1 file 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/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 interface. The new_session_cb() is called whenever a new session has been negotiated and session caching is enabled (see L). The -new_session_cb() is passed the B connection and the ssl session B. +new_session_cb() is passed the B connection and the nascent +ssl session B. 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 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 is called. The remove_session_cb() is passed the B and the ssl session B. 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 connection, the session id of length B at the memory location -B. With the parameter B 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 connection and the session id of length B at the memory location +B. By setting the parameter B to B<1>, the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object; +setting B to B<0> causes the reference count to remain unchanged. +If the get_session_cb() does not write to B, the reference count +is incremented and the session must be explicitly freed with L. =head1 RETURN VALUES -- 2.25.1