Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "SSL_CTX_SESS_SET_GET_CB 3"
way too many mistakes in technical documents.
\fBSSL_CTX_sess_set_remove_cb() sets the callback function that is called whenever a session is removed by the \s-1SSL\s0 engine. For example, this can occur because a session is considered faulty or has become obsolete because of exceeding the timeout value.
\fBSSL_CTX_sess_set_get_cb() sets the callback function that is called whenever a \s-1TLS\s0 client proposed to resume a session but the session could not be found in the internal session cache (see \fBSSL_CTX_set_session_cache_mode\|(3)). (\s-1TLS\s0 server only.)
\fBSSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and \fBSSL_CTX_sess_get_get_cb() retrieve the function pointers set by the corresponding set callback functions. If a callback function has not been set, the \s-1NULL\s0 pointer is returned.
The new_session_cb() is called whenever a new session has been negotiated and session caching is enabled (see SSL_CTX_set_session_cache_mode\|(3)). The \fBnew_session_cb() is passed the ssl connection and the nascent ssl session 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 0, the session will be immediately removed from the internal cache and the reference count released. If the callback returns 1, the application retains the reference (for an entry in the application-maintained \*(L"external session cache\*(R"), and is responsible for calling SSL_SESSION_free() when the session reference is no longer in use.
Note that in TLSv1.3, sessions are established after the main handshake has completed. The server decides when to send the client the session information and this may occur some time after the end of the handshake (or not at all). This means that applications should expect the new_session_cb() function to be invoked during the handshake (for <= TLSv1.2) or after the handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to be established with a single connection. In these case the new_session_cb() function will be invoked multiple times.
In TLSv1.3 it is recommended that each \s-1SSL_SESSION\s0 object is only used for resumption once. One way of enforcing that is for applications to call \fBSSL_CTX_remove_session\|(3) after a session has been used.
The remove_session_cb() is called whenever the \s-1SSL\s0 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 \fBSSL_CTX_free\|(3) is called. The remove_session_cb() is passed the ctx and the ssl session sess. It does not provide any feedback.
The get_session_cb() is only called on \s-1SSL/TLS\s0 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 \fBssl connection and the session id of length length at the memory location \fBdata. By setting the parameter copy to 1, the callback can require the \s-1SSL\s0 engine to increment the reference count of the \s-1SSL_SESSION\s0 object; setting copy to 0 causes the reference count to remain unchanged. If the get_session_cb() does not write to copy, the reference count is incremented and the session must be explicitly freed with \fBSSL_SESSION_free\|(3).
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.