secure/lib/libcrypto/man/SSL_CTX_sess_set_get_cb.3

   1 .\" Automatically generated by Pod::Man 4.09 (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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_SESS_SET_GET_CB 3"
 132 .TH SSL_CTX_SESS_SET_GET_CB 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
 145 \&                              int (*new_session_cb)(SSL *, SSL_SESSION *));
 146 \& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
 147 \&                                 void (*remove_session_cb)(SSL_CTX *ctx,
 148 \&                                                           SSL_SESSION *));
 149 \& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
 150 \&                              SSL_SESSION (*get_session_cb)(SSL *,
 151 \&                                                            const unsigned char *,
 152 \&                                                            int, int *));
 153 \&
 154 \& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl,
 155 \&                                              SSL_SESSION *sess);
 156 \& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx,
 157 \&                                                  SSL_SESSION *sess);
 158 \& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl,
 159 \&                                                       const unsigned char *data,
 160 \&                                                       int len, int *copy);
 161 .Ve
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 \&\fISSL_CTX_sess_set_new_cb()\fR sets the callback function, which is automatically
 165 called whenever a new session was negotiated.
 166 .PP
 167 \&\fISSL_CTX_sess_set_remove_cb()\fR sets the callback function, which is
 168 automatically called whenever a session is removed by the \s-1SSL\s0 engine,
 169 because it is considered faulty or the session has become obsolete because
 170 of exceeding the timeout value.
 171 .PP
 172 \&\fISSL_CTX_sess_set_get_cb()\fR sets the callback function which is called,
 173 whenever a \s-1SSL/TLS\s0 client proposed to resume a session but the session
 174 could not be found in the internal session cache (see
 175 \&\fISSL_CTX_set_session_cache_mode\fR\|(3)).
 176 (\s-1SSL/TLS\s0 server only.)
 177 .PP
 178 \&\fISSL_CTX_sess_get_new_cb()\fR, \fISSL_CTX_sess_get_remove_cb()\fR, and
 179 \&\fISSL_CTX_sess_get_get_cb()\fR retrieve the function pointers set by the
 180 corresponding set callback functions. If a callback function has not been
 181 set, the \s-1NULL\s0 pointer is returned.
 182 .SH "NOTES"
 183 .IX Header "NOTES"
 184 In order to allow external session caching, synchronization with the internal
 185 session cache is realized via callback functions. Inside these callback
 186 functions, session can be saved to disk or put into a database using the
 187 \&\fId2i_SSL_SESSION\fR\|(3) interface.
 188 .PP
 189 The \fInew_session_cb()\fR is called, whenever a new session has been negotiated
 190 and session caching is enabled (see
 191 \&\fISSL_CTX_set_session_cache_mode\fR\|(3)).
 192 The \fInew_session_cb()\fR is passed the \fBssl\fR connection and the ssl session
 193 \&\fBsess\fR. If the callback returns \fB0\fR, the session will be immediately
 194 removed again. Note that in TLSv1.3, sessions are established after the main
 195 handshake has completed. The server decides when to send the client the session
 196 information and this may occur some time after the end of the handshake (or not
 197 at all). This means that applications should expect the \fInew_session_cb()\fR
 198 function to be invoked during the handshake (for <= TLSv1.2) or after the
 199 handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to
 200 be established with a single connection. In these case the \fInew_session_cb()\fR
 201 function will be invoked multiple times.
 202 .PP
 203 In TLSv1.3 it is recommended that each \s-1SSL_SESSION\s0 object is only used for
 204 resumption once. One way of enforcing that is for applications to call
 205 \&\fISSL_CTX_remove_session\fR\|(3) after a session has been used.
 206 .PP
 207 The \fIremove_session_cb()\fR is called, whenever the \s-1SSL\s0 engine removes a session
 208 from the internal cache. This happens when the session is removed because
 209 it is expired or when a connection was not shutdown cleanly. It also happens
 210 for all sessions in the internal session cache when
 211 \&\fISSL_CTX_free\fR\|(3) is called. The \fIremove_session_cb()\fR is passed
 212 the \fBctx\fR and the ssl session \fBsess\fR. It does not provide any feedback.
 213 .PP
 214 The \fIget_session_cb()\fR is only called on \s-1SSL/TLS\s0 servers with the session id
 215 proposed by the client. The \fIget_session_cb()\fR is always called, also when
 216 session caching was disabled. The \fIget_session_cb()\fR is passed the
 217 \&\fBssl\fR connection, the session id of length \fBlength\fR at the memory location
 218 \&\fBdata\fR. With the parameter \fBcopy\fR the callback can require the
 219 \&\s-1SSL\s0 engine to increment the reference count of the \s-1SSL_SESSION\s0 object,
 220 Normally the reference count is not incremented and therefore the
 221 session must not be explicitly freed with
 222 \&\fISSL_SESSION_free\fR\|(3).
 223 .SH "RETURN VALUES"
 224 .IX Header "RETURN VALUES"
 225 \&\fISSL_CTX_sess_get_new_cb()\fR, \fISSL_CTX_sess_get_remove_cb()\fR and \fISSL_CTX_sess_get_get_cb()\fR
 226 return different callback function pointers respectively.
 227 .SH "SEE ALSO"
 228 .IX Header "SEE ALSO"
 229 \&\fIssl\fR\|(7), \fId2i_SSL_SESSION\fR\|(3),
 230 \&\fISSL_CTX_set_session_cache_mode\fR\|(3),
 231 \&\fISSL_CTX_flush_sessions\fR\|(3),
 232 \&\fISSL_SESSION_free\fR\|(3),
 233 \&\fISSL_CTX_free\fR\|(3)
 234 .SH "COPYRIGHT"
 235 .IX Header "COPYRIGHT"
 236 Copyright 2001\-2018 The OpenSSL Project Authors. All Rights Reserved.
 237 .PP
 238 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 239 this file except in compliance with the License.  You can obtain a copy
 240 in the file \s-1LICENSE\s0 in the source distribution or at
 241 <https://www.openssl.org/source/license.html>.