secure/lib/libssl/man/SSL_CTX_sess_set_get_cb.3

   1 .\" Automatically generated by Pod::Man version 1.15
   2 .\" Wed Feb 19 16:47:39 2003
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` ""
  50 .    ds C' ""
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 ..
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .if n .na
  75 .\"
  76 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  77 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  78 .bd B 3
  79 .    \" fudge factors for nroff and troff
  80 .if n \{\
  81 .    ds #H 0
  82 .    ds #V .8m
  83 .    ds #F .3m
  84 .    ds #[ \f1
  85 .    ds #] \fP
  86 .\}
  87 .if t \{\
  88 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  89 .    ds #V .6m
  90 .    ds #F 0
  91 .    ds #[ \&
  92 .    ds #] \&
  93 .\}
  94 .    \" simple accents for nroff and troff
  95 .if n \{\
  96 .    ds ' \&
  97 .    ds ` \&
  98 .    ds ^ \&
  99 .    ds , \&
 100 .    ds ~ ~
 101 .    ds /
 102 .\}
 103 .if t \{\
 104 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 105 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 106 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 107 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 108 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 109 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 110 .\}
 111 .    \" troff and (daisy-wheel) nroff accents
 112 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 113 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 114 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 115 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 116 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 117 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 118 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 119 .ds ae a\h'-(\w'a'u*4/10)'e
 120 .ds Ae A\h'-(\w'A'u*4/10)'E
 121 .    \" corrections for vroff
 122 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 123 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 124 .    \" for low resolution devices (crt and lpr)
 125 .if \n(.H>23 .if \n(.V>19 \
 126 \{\
 127 .    ds : e
 128 .    ds 8 ss
 129 .    ds o a
 130 .    ds d- d\h'-1'\(ga
 131 .    ds D- D\h'-1'\(hy
 132 .    ds th \o'bp'
 133 .    ds Th \o'LP'
 134 .    ds ae ae
 135 .    ds Ae AE
 136 .\}
 137 .rm #[ #] #H #V #F C
 138 .\" ======================================================================
 139 .\"
 140 .IX Title "SSL_CTX_sess_set_get_cb 3"
 141 .TH SSL_CTX_sess_set_get_cb 3 "0.9.7a" "2003-02-19" "OpenSSL"
 142 .UC
 143 .SH "NAME"
 144 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
 145 .SH "SYNOPSIS"
 146 .IX Header "SYNOPSIS"
 147 .Vb 1
 148 \& #include <openssl/ssl.h>
 149 .Ve
 150 .Vb 6
 151 \& void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,
 152 \&                              int (*new_session_cb)(SSL *, SSL_SESSION *));
 153 \& void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx,
 154 \&           void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *));
 155 \& void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
 156 \&           SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *));
 157 .Ve
 158 .Vb 3
 159 \& int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess);
 160 \& void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
 161 \& SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy);
 162 .Ve
 163 .Vb 4
 164 \& int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess);
 165 \& void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess);
 166 \& SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data,
 167 \&               int len, int *copy);
 168 .Ve
 169 .SH "DESCRIPTION"
 170 .IX Header "DESCRIPTION"
 171 \&\fISSL_CTX_sess_set_new_cb()\fR sets the callback function, which is automatically
 172 called whenever a new session was negotiated.
 173 .PP
 174 \&\fISSL_CTX_sess_set_remove_cb()\fR sets the callback function, which is
 175 automatically called whenever a session is removed by the \s-1SSL\s0 engine,
 176 because it is considered faulty or the session has become obsolete because
 177 of exceeding the timeout value.
 178 .PP
 179 \&\fISSL_CTX_sess_set_get_cb()\fR sets the callback function which is called,
 180 whenever a \s-1SSL/TLS\s0 client proposed to resume a session but the session
 181 could not be found in the internal session cache (see
 182 SSL_CTX_set_session_cache_mode(3)).
 183 (\s-1SSL/TLS\s0 server only.)
 184 .PP
 185 \&\fISSL_CTX_sess_get_new_cb()\fR, \fISSL_CTX_sess_get_remove_cb()\fR, and
 186 \&\fISSL_CTX_sess_get_get_cb()\fR allow to retrieve the function pointers of the
 187 provided callback functions. If a callback function has not been set,
 188 the \s-1NULL\s0 pointer is returned.
 189 .SH "NOTES"
 190 .IX Header "NOTES"
 191 In order to allow external session caching, synchronization with the internal
 192 session cache is realized via callback functions. Inside these callback
 193 functions, session can be saved to disk or put into a database using the
 194 d2i_SSL_SESSION(3) interface.
 195 .PP
 196 The \fInew_session_cb()\fR is called, whenever a new session has been negotiated
 197 and session caching is enabled (see
 198 SSL_CTX_set_session_cache_mode(3)).
 199 The \fInew_session_cb()\fR is passed the \fBssl\fR connection and the ssl session
 200 \&\fBsess\fR. If the callback returns \fB0\fR, the session will be immediately
 201 removed again.
 202 .PP
 203 The \fIremove_session_cb()\fR is called, whenever the \s-1SSL\s0 engine removes a session
 204 from the internal cache. This happens if the session is removed because
 205 it is expired or when a connection was not shutdown cleanly. The
 206 \&\fIremove_session_cb()\fR is passed the \fBctx\fR and the ssl session \fBsess\fR.
 207 It does not provide any feedback.
 208 .PP
 209 The \fIget_session_cb()\fR is only called on \s-1SSL/TLS\s0 servers with the session id
 210 proposed by the client. The \fIget_session_cb()\fR is always called, also when
 211 session caching was disabled. The \fIget_session_cb()\fR is passed the
 212 \&\fBssl\fR connection, the session id of length \fBlength\fR at the memory location
 213 \&\fBdata\fR. With the parameter \fBcopy\fR the callback can require the
 214 \&\s-1SSL\s0 engine to increment the reference count of the \s-1SSL_SESSION\s0 object,
 215 Normally the reference count is not incremented and therefore the
 216 session must not be explicitly freed with
 217 SSL_SESSION_free(3).
 218 .SH "SEE ALSO"
 219 .IX Header "SEE ALSO"
 220 ssl(3), d2i_SSL_SESSION(3),
 221 SSL_CTX_set_session_cache_mode(3),
 222 SSL_CTX_flush_sessions(3),
 223 SSL_SESSION_free(3)