secure/lib/libcrypto/man/SSL_CTX_sess_set_get_cb.3

   1 .\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
   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 "2019-05-28" "1.1.1c" "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, which is automatically
 169 called whenever a new session was negotiated.
 170 .PP
 171 \&\fBSSL_CTX_sess_set_remove_cb()\fR sets the callback function, which is
 172 automatically called whenever a session is removed by the \s-1SSL\s0 engine,
 173 because it is considered faulty or the session has become obsolete because
 174 of exceeding the timeout value.
 175 .PP
 176 \&\fBSSL_CTX_sess_set_get_cb()\fR sets the callback function which is called,
 177 whenever a \s-1SSL/TLS\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-1SSL/TLS\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
 194 and session caching is enabled (see
 195 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3)).
 196 The \fBnew_session_cb()\fR is passed the \fBssl\fR connection and the ssl session
 197 \&\fBsess\fR. If the callback returns \fB0\fR, the session will be immediately
 198 removed again. Note that in TLSv1.3, sessions are established after the main
 199 handshake has completed. The server decides when to send the client the session
 200 information and this may occur some time after the end of the handshake (or not
 201 at all). This means that applications should expect the \fBnew_session_cb()\fR
 202 function to be invoked during the handshake (for <= TLSv1.2) or after the
 203 handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to
 204 be established with a single connection. In these case the \fBnew_session_cb()\fR
 205 function will be invoked multiple times.
 206 .PP
 207 In TLSv1.3 it is recommended that each \s-1SSL_SESSION\s0 object is only used for
 208 resumption once. One way of enforcing that is for applications to call
 209 \&\fBSSL_CTX_remove_session\fR\|(3) after a session has been used.
 210 .PP
 211 The \fBremove_session_cb()\fR is called, whenever the \s-1SSL\s0 engine removes a session
 212 from the internal cache. This happens when the session is removed because
 213 it is expired or when a connection was not shutdown cleanly. It also happens
 214 for all sessions in the internal session cache when
 215 \&\fBSSL_CTX_free\fR\|(3) is called. The \fBremove_session_cb()\fR is passed
 216 the \fBctx\fR and the ssl session \fBsess\fR. It does not provide any feedback.
 217 .PP
 218 The \fBget_session_cb()\fR is only called on \s-1SSL/TLS\s0 servers with the session id
 219 proposed by the client. The \fBget_session_cb()\fR is always called, also when
 220 session caching was disabled. The \fBget_session_cb()\fR is passed the
 221 \&\fBssl\fR connection, the session id of length \fBlength\fR at the memory location
 222 \&\fBdata\fR. With the parameter \fBcopy\fR the callback can require the
 223 \&\s-1SSL\s0 engine to increment the reference count of the \s-1SSL_SESSION\s0 object,
 224 Normally the reference count is not incremented and therefore the
 225 session must not be explicitly freed with
 226 \&\fBSSL_SESSION_free\fR\|(3).
 227 .SH "RETURN VALUES"
 228 .IX Header "RETURN VALUES"
 229 \&\fBSSL_CTX_sess_get_new_cb()\fR, \fBSSL_CTX_sess_get_remove_cb()\fR and \fBSSL_CTX_sess_get_get_cb()\fR
 230 return different callback function pointers respectively.
 231 .SH "SEE ALSO"
 232 .IX Header "SEE ALSO"
 233 \&\fBssl\fR\|(7), \fBd2i_SSL_SESSION\fR\|(3),
 234 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3),
 235 \&\fBSSL_CTX_flush_sessions\fR\|(3),
 236 \&\fBSSL_SESSION_free\fR\|(3),
 237 \&\fBSSL_CTX_free\fR\|(3)
 238 .SH "COPYRIGHT"
 239 .IX Header "COPYRIGHT"
 240 Copyright 2001\-2018 The OpenSSL Project Authors. All Rights Reserved.
 241 .PP
 242 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 243 this file except in compliance with the License.  You can obtain a copy
 244 in the file \s-1LICENSE\s0 in the source distribution or at
 245 <https://www.openssl.org/source/license.html>.