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)

diff --git a/doc/man3/SSL_CTX_sess_set_get_cb.pod b/doc/man3/SSL_CTX_sess_set_get_cb.pod
index 11eda7e141108e62c05a3e6a0c1fde3f03662969..1b0f8a341b8510c033f7d541bc6b7871bf5a79a9 100644 (file)
--- 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