secure/lib/libssl/man/SSL_CTX_sess_set_get_cb.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH SSL_CTX_sess_set_get_cb 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 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
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 1
 195 \& #include <openssl/ssl.h>
 196 .Ve
 197 .Vb 6
 198 \& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
 199 \&                              int (*new_session_cb)(SSL *, SSL_SESSION *));
 200 \& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
 201 \&           void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
 202 \& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
 203 \&           SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *));
 204 .Ve
 205 .Vb 3
 206 \& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
 207 \& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
 208 \& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy);
 209 .Ve
 210 .Vb 4
 211 \& int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
 212 \& void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
 213 \& SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
 214 \&               int len, int *copy);
 215 .Ve
 216 .SH "DESCRIPTION"
 217 \fISSL_CTX_sess_set_new_cb()\fR sets the callback function, which is automatically
 218 called whenever a new session was negotiated.
 219 .PP
 220 \fISSL_CTX_sess_set_remove_cb()\fR sets the callback function, which is
 221 automatically called whenever a session is removed by the SSL engine,
 222 because it is considered faulty or the session has become obsolete because
 223 of exceeding the timeout value.
 224 .PP
 225 \fISSL_CTX_sess_set_get_cb()\fR sets the callback function which is called,
 226 whenever a SSL/TLS client proposed to resume a session but the session
 227 could not be found in the internal session cache (see
 228 SSL_CTX_set_session_cache_mode(3)).
 229 (SSL/TLS server only.)
 230 .PP
 231 \fISSL_CTX_sess_get_new_cb()\fR, \fISSL_CTX_sess_get_remove_cb()\fR, and
 232 \fISSL_CTX_sess_get_get_cb()\fR allow to retrieve the function pointers of the
 233 provided callback functions. If a callback function has not been set,
 234 the NULL pointer is returned.
 235 .SH "NOTES"
 236 In order to allow external session caching, synchronization with the internal
 237 session cache is realized via callback functions. Inside these callback
 238 functions, session can be saved to disk or put into a database using the
 239 d2i_SSL_SESSION(3) interface.
 240 .PP
 241 The \fInew_session_cb()\fR is called, whenever a new session has been negotiated
 242 and session caching is enabled (see
 243 SSL_CTX_set_session_cache_mode(3)).
 244 The \fInew_session_cb()\fR is passed the \fBssl\fR connection and the ssl session
 245 \fBsess\fR. If the callback returns \fB0\fR, the session will be immediately
 246 removed again.
 247 .PP
 248 The \fIremove_session_cb()\fR is called, whenever the SSL engine removes a session
 249 from the internal cache. This happens when the session is removed because
 250 it is expired or when a connection was not shutdown cleanly. It also happens
 251 for all sessions in the internal session cache when
 252 SSL_CTX_free(3) is called. The \fIremove_session_cb()\fR is passed
 253 the \fBctx\fR and the ssl session \fBsess\fR. It does not provide any feedback.
 254 .PP
 255 The \fIget_session_cb()\fR is only called on SSL/TLS servers with the session id
 256 proposed by the client. The \fIget_session_cb()\fR is always called, also when
 257 session caching was disabled. The \fIget_session_cb()\fR is passed the
 258 \fBssl\fR connection, the session id of length \fBlength\fR at the memory location
 259 \fBdata\fR. With the parameter \fBcopy\fR the callback can require the
 260 SSL engine to increment the reference count of the SSL_SESSION object,
 261 Normally the reference count is not incremented and therefore the
 262 session must not be explicitly freed with
 263 SSL_SESSION_free(3).
 264 .SH "SEE ALSO"
 265 ssl(3), d2i_SSL_SESSION(3),
 266 SSL_CTX_set_session_cache_mode(3),
 267 SSL_CTX_flush_sessions(3),
 268 SSL_SESSION_free(3),
 269 SSL_CTX_free(3)
 270
 271 .rn }` ''
 272 .IX Title "SSL_CTX_sess_set_get_cb 3"
 273 .IX Name "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"
 274
 275 .IX Header "NAME"
 276
 277 .IX Header "SYNOPSIS"
 278
 279 .IX Header "DESCRIPTION"
 280
 281 .IX Header "NOTES"
 282
 283 .IX Header "SEE ALSO"
 284