secure/lib/libssl/man/SSL_CTX_set_session_cache_mode.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_set_session_cache_mode 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_set_session_cache_mode, SSL_CTX_get_session_cache_mode \- enable/disable session caching
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 1
 195 \& #include <openssl/ssl.h>
 196 .Ve
 197 .Vb 2
 198 \& long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode);
 199 \& long SSL_CTX_get_session_cache_mode(SSL_CTX ctx);
 200 .Ve
 201 .SH "DESCRIPTION"
 202 \fISSL_CTX_set_session_cache_mode()\fR enables/disables session caching
 203 by setting the operational mode for \fBctx\fR to <mode>.
 204 .PP
 205 \fISSL_CTX_get_session_cache_mode()\fR returns the currently used cache mode.
 206 .SH "NOTES"
 207 The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
 208 The sessions can be held in memory for each \fBctx\fR, if more than one
 209 SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
 210 object.
 211 .PP
 212 In order to reuse a session, a client must send the session's id to the
 213 server. It can only send exactly one id.  The server then either
 214 agrees to reuse the session or it starts a full handshake (to create a new
 215 session).
 216 .PP
 217 A server will lookup up the session in its internal session storage. If the
 218 session is not found in internal storage or lookups for the internal storage
 219 have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try
 220 the external storage if available.
 221 .PP
 222 Since a client may try to reuse a session intended for use in a different
 223 context, the session id context must be set by the server (see
 224 SSL_CTX_set_session_id_context(3)).
 225 .PP
 226 The following session cache modes and modifiers are available:
 227 .Ip "\s-1SSL_SESS_CACHE_OFF\s0" 4
 228 No session caching for client or server takes place.
 229 .Ip "\s-1SSL_SESS_CACHE_CLIENT\s0" 4
 230 Client sessions are added to the session cache. As there is no reliable way
 231 for the OpenSSL library to know whether a session should be reused or which
 232 session to choose (due to the abstract \s-1BIO\s0 layer the \s-1SSL\s0 engine does not
 233 have details about the connection), the application must select the session
 234 to be reused by using the SSL_set_session(3)
 235 function. This option is not activated by default.
 236 .Ip "\s-1SSL_SESS_CACHE_SERVER\s0" 4
 237 Server sessions are added to the session cache. When a client proposes a
 238 session to be reused, the server looks for the corresponding session in (first)
 239 the internal session cache (unless \s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0 is set),
 240 then (second) in the external cache if available. If the session is found, the
 241 server will try to reuse the session.  This is the default.
 242 .Ip "\s-1SSL_SESS_CACHE_BOTH\s0" 4
 243 Enable both \s-1SSL_SESS_CACHE_CLIENT\s0 and \s-1SSL_SESS_CACHE_SERVER\s0 at the same time.
 244 .Ip "\s-1SSL_SESS_CACHE_NO_AUTO_CLEAR\s0" 4
 245 Normally the session cache is checked for expired sessions every
 246 255 connections using the
 247 SSL_CTX_flush_sessions(3) function. Since
 248 this may lead to a delay which cannot be controlled, the automatic
 249 flushing may be disabled and
 250 SSL_CTX_flush_sessions(3) can be called
 251 explicitly by the application.
 252 .Ip "\s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0" 4
 253 By setting this flag, session-resume operations in an \s-1SSL/TLS\s0 server will not
 254 automatically look up sessions in the internal cache, even if sessions are
 255 automatically stored there. If external session caching callbacks are in use,
 256 this flag guarantees that all lookups are directed to the external cache.
 257 As automatic lookup only applies for \s-1SSL/TLS\s0 servers, the flag has no effect on
 258 clients.
 259 .Ip "\s-1SSL_SESS_CACHE_NO_INTERNAL_STORE\s0" 4
 260 Depending on the presence of \s-1SSL_SESS_CACHE_CLIENT\s0 and/or \s-1SSL_SESS_CACHE_SERVER\s0,
 261 sessions negotiated in an \s-1SSL/TLS\s0 handshake may be cached for possible reuse.
 262 Normally a new session is added to the internal cache as well as any external
 263 session caching (callback) that is configured for the \s-1SSL_CTX\s0. This flag will
 264 prevent sessions being stored in the internal cache (though the application can
 265 add them manually using SSL_CTX_add_session(3)). Note:
 266 in any \s-1SSL/TLS\s0 servers where external caching is configured, any successful
 267 session lookups in the external cache (ie. for session-resume requests) would
 268 normally be copied into the local cache before processing continues \- this flag
 269 prevents these additions to the internal cache as well.
 270 .Ip "\s-1SSL_SESS_CACHE_NO_INTERNAL\s0" 4
 271 Enable both \s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0 and
 272 \s-1SSL_SESS_CACHE_NO_INTERNAL_STORE\s0 at the same time.
 273 .PP
 274 The default mode is \s-1SSL_SESS_CACHE_SERVER\s0.
 275 .SH "RETURN VALUES"
 276 \fISSL_CTX_set_session_cache_mode()\fR returns the previously set cache mode.
 277 .PP
 278 \fISSL_CTX_get_session_cache_mode()\fR returns the currently set cache mode.
 279 .SH "SEE ALSO"
 280 ssl(3), SSL_set_session(3),
 281 SSL_session_reused(3),
 282 SSL_CTX_add_session(3),
 283 SSL_CTX_sess_number(3),
 284 SSL_CTX_sess_set_cache_size(3),
 285 SSL_CTX_sess_set_get_cb(3),
 286 SSL_CTX_set_session_id_context(3),
 287 SSL_CTX_set_timeout(3),
 288 SSL_CTX_flush_sessions(3)
 289 .SH "HISTORY"
 290 SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL
 291 were introduced in OpenSSL 0.9.6h.
 292
 293 .rn }` ''
 294 .IX Title "SSL_CTX_set_session_cache_mode 3"
 295 .IX Name "SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching"
 296
 297 .IX Header "NAME"
 298
 299 .IX Header "SYNOPSIS"
 300
 301 .IX Header "DESCRIPTION"
 302
 303 .IX Header "NOTES"
 304
 305 .IX Item "\s-1SSL_SESS_CACHE_OFF\s0"
 306
 307 .IX Item "\s-1SSL_SESS_CACHE_CLIENT\s0"
 308
 309 .IX Item "\s-1SSL_SESS_CACHE_SERVER\s0"
 310
 311 .IX Item "\s-1SSL_SESS_CACHE_BOTH\s0"
 312
 313 .IX Item "\s-1SSL_SESS_CACHE_NO_AUTO_CLEAR\s0"
 314
 315 .IX Item "\s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0"
 316
 317 .IX Item "\s-1SSL_SESS_CACHE_NO_INTERNAL_STORE\s0"
 318
 319 .IX Item "\s-1SSL_SESS_CACHE_NO_INTERNAL\s0"
 320
 321 .IX Header "RETURN VALUES"
 322
 323 .IX Header "SEE ALSO"
 324
 325 .IX Header "HISTORY"
 326