secure/lib/libcrypto/man/man3/SSL_CTX_sess_set_get_cb.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_SESS_SET_GET_CB 3"
 136 .TH SSL_CTX_SESS_SET_GET_CB 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb \- provide callback functions for server side external session caching
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
 149 \&                              int (*new_session_cb)(SSL *, SSL_SESSION *));
 150 \& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
 151 \&                                 void (*remove_session_cb)(SSL_CTX *ctx,
 152 \&                                                           SSL_SESSION *));
 153 \& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
 154 \&                              SSL_SESSION (*get_session_cb)(SSL *,
 155 \&                                                            const unsigned char *,
 156 \&                                                            int, int *));
 157 \&
 158 \& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl,
 159 \&                                              SSL_SESSION *sess);
 160 \& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx,
 161 \&                                                  SSL_SESSION *sess);
 162 \& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl,
 163 \&                                                       const unsigned char *data,
 164 \&                                                       int len, int *copy);
 165 .Ve
 166 .SH "DESCRIPTION"
 167 .IX Header "DESCRIPTION"
 168 \&\fBSSL_CTX_sess_set_new_cb()\fR sets the callback function that is
 169 called whenever a new session was negotiated.
 170 .PP
 171 \&\fBSSL_CTX_sess_set_remove_cb()\fR sets the callback function that is
 172 called whenever a session is removed by the \s-1SSL\s0 engine.  For example,
 173 this can occur because a session is considered faulty or has become obsolete
 174 because of exceeding the timeout value.
 175 .PP
 176 \&\fBSSL_CTX_sess_set_get_cb()\fR sets the callback function that is called
 177 whenever a \s-1TLS\s0 client proposed to resume a session but the session
 178 could not be found in the internal session cache (see
 179 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3)).
 180 (\s-1TLS\s0 server only.)
 181 .PP
 182 \&\fBSSL_CTX_sess_get_new_cb()\fR, \fBSSL_CTX_sess_get_remove_cb()\fR, and
 183 \&\fBSSL_CTX_sess_get_get_cb()\fR retrieve the function pointers set by the
 184 corresponding set callback functions. If a callback function has not been
 185 set, the \s-1NULL\s0 pointer is returned.
 186 .SH "NOTES"
 187 .IX Header "NOTES"
 188 In order to allow external session caching, synchronization with the internal
 189 session cache is realized via callback functions. Inside these callback
 190 functions, session can be saved to disk or put into a database using the
 191 \&\fBd2i_SSL_SESSION\fR\|(3) interface.
 192 .PP
 193 The \fBnew_session_cb()\fR is called whenever a new session has been negotiated and
 194 session caching is enabled (see \fBSSL_CTX_set_session_cache_mode\fR\|(3)).  The
 195 \&\fBnew_session_cb()\fR is passed the \fBssl\fR connection and the nascent
 196 ssl session \fBsess\fR.
 197 Since sessions are reference-counted objects, the reference count on the
 198 session is incremented before the callback, on behalf of the application.  If
 199 the callback returns \fB0\fR, the session will be immediately removed from the
 200 internal cache and the reference count released. If the callback returns \fB1\fR,
 201 the application retains the reference (for an entry in the
 202 application-maintained \*(L"external session cache\*(R"), and is responsible for
 203 calling \fBSSL_SESSION_free()\fR when the session reference is no longer in use.
 204 .PP
 205 Note that in TLSv1.3, sessions are established after the main
 206 handshake has completed. The server decides when to send the client the session
 207 information and this may occur some time after the end of the handshake (or not
 208 at all). This means that applications should expect the \fBnew_session_cb()\fR
 209 function to be invoked during the handshake (for <= TLSv1.2) or after the
 210 handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to
 211 be established with a single connection. In these case the \fBnew_session_cb()\fR
 212 function will be invoked multiple times.
 213 .PP
 214 In TLSv1.3 it is recommended that each \s-1SSL_SESSION\s0 object is only used for
 215 resumption once. One way of enforcing that is for applications to call
 216 \&\fBSSL_CTX_remove_session\fR\|(3) after a session has been used.
 217 .PP
 218 The \fBremove_session_cb()\fR is called whenever the \s-1SSL\s0 engine removes a session
 219 from the internal cache. This can happen when the session is removed because
 220 it is expired or when a connection was not shutdown cleanly. It also happens
 221 for all sessions in the internal session cache when
 222 \&\fBSSL_CTX_free\fR\|(3) is called. The \fBremove_session_cb()\fR is passed
 223 the \fBctx\fR and the ssl session \fBsess\fR. It does not provide any feedback.
 224 .PP
 225 The \fBget_session_cb()\fR is only called on \s-1SSL/TLS\s0 servers, and is given
 226 the session id
 227 proposed by the client. The \fBget_session_cb()\fR is always called, even when
 228 session caching was disabled. The \fBget_session_cb()\fR is passed the
 229 \&\fBssl\fR connection and the session id of length \fBlength\fR at the memory location
 230 \&\fBdata\fR. By setting the parameter \fBcopy\fR to \fB1\fR, the callback can require the
 231 \&\s-1SSL\s0 engine to increment the reference count of the \s-1SSL_SESSION\s0 object;
 232 setting \fBcopy\fR to \fB0\fR causes the reference count to remain unchanged.
 233 If the \fBget_session_cb()\fR does not write to \fBcopy\fR, the reference count
 234 is incremented and the session must be explicitly freed with
 235 \&\fBSSL_SESSION_free\fR\|(3).
 236 .SH "RETURN VALUES"
 237 .IX Header "RETURN VALUES"
 238 \&\fBSSL_CTX_sess_get_new_cb()\fR, \fBSSL_CTX_sess_get_remove_cb()\fR and \fBSSL_CTX_sess_get_get_cb()\fR
 239 return different callback function pointers respectively.
 240 .SH "SEE ALSO"
 241 .IX Header "SEE ALSO"
 242 \&\fBssl\fR\|(7), \fBd2i_SSL_SESSION\fR\|(3),
 243 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3),
 244 \&\fBSSL_CTX_flush_sessions\fR\|(3),
 245 \&\fBSSL_SESSION_free\fR\|(3),
 246 \&\fBSSL_CTX_free\fR\|(3)
 247 .SH "COPYRIGHT"
 248 .IX Header "COPYRIGHT"
 249 Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved.
 250 .PP
 251 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 252 this file except in compliance with the License.  You can obtain a copy
 253 in the file \s-1LICENSE\s0 in the source distribution or at
 254 <https://www.openssl.org/source/license.html>.