Remove my local patch again, it was still not meant to be commited.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_session_cache_mode.3
CommitLineData
a7d27d5a
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
a7d27d5a 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
a7d27d5a 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
a7d27d5a 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
a7d27d5a 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
a7d27d5a
JR
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'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
a7d27d5a
JR
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' '
984263bc
MD
62'br\}
63.el\{\
a7d27d5a
JR
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
984263bc 79'br\}
a7d27d5a
JR
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"
984263bc 92..
a7d27d5a
JR
93.nr % 0
94.rr F
984263bc 95.\}
a7d27d5a
JR
96.TH SSL_CTX_set_session_cache_mode 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
a7d27d5a
JR
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
984263bc 112.bd B 3
a7d27d5a 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
a7d27d5a
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
a7d27d5a
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
a7d27d5a 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
a7d27d5a
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
a7d27d5a
JR
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'
984263bc 150.\}
a7d27d5a 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
a7d27d5a
JR
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'\*(#]
984263bc
MD
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
a7d27d5a
JR
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
984263bc
MD
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'
a7d27d5a 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
a7d27d5a
JR
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
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode \- enable/disable session caching
192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
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"
a7d27d5a 202\fISSL_CTX_set_session_cache_mode()\fR enables/disables session caching
984263bc
MD
203by setting the operational mode for \fBctx\fR to <mode>.
204.PP
a7d27d5a 205\fISSL_CTX_get_session_cache_mode()\fR returns the currently used cache mode.
984263bc 206.SH "NOTES"
a7d27d5a 207The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
984263bc 208The sessions can be held in memory for each \fBctx\fR, if more than one
a7d27d5a 209SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
984263bc
MD
210object.
211.PP
212In order to reuse a session, a client must send the session's id to the
213server. It can only send exactly one id. The server then either
214agrees to reuse the session or it starts a full handshake (to create a new
215session).
216.PP
217A server will lookup up the session in its internal session storage. If the
218session is not found in internal storage or lookups for the internal storage
a7d27d5a 219have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try
984263bc
MD
220the external storage if available.
221.PP
222Since a client may try to reuse a session intended for use in a different
223context, the session id context must be set by the server (see
224SSL_CTX_set_session_id_context(3)).
225.PP
226The following session cache modes and modifiers are available:
227.Ip "\s-1SSL_SESS_CACHE_OFF\s0" 4
984263bc
MD
228No session caching for client or server takes place.
229.Ip "\s-1SSL_SESS_CACHE_CLIENT\s0" 4
984263bc
MD
230Client sessions are added to the session cache. As there is no reliable way
231for the OpenSSL library to know whether a session should be reused or which
232session to choose (due to the abstract \s-1BIO\s0 layer the \s-1SSL\s0 engine does not
233have details about the connection), the application must select the session
234to be reused by using the SSL_set_session(3)
235function. This option is not activated by default.
236.Ip "\s-1SSL_SESS_CACHE_SERVER\s0" 4
984263bc
MD
237Server sessions are added to the session cache. When a client proposes a
238session to be reused, the server looks for the corresponding session in (first)
239the internal session cache (unless \s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0 is set),
240then (second) in the external cache if available. If the session is found, the
241server will try to reuse the session. This is the default.
242.Ip "\s-1SSL_SESS_CACHE_BOTH\s0" 4
984263bc
MD
243Enable 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
984263bc
MD
245Normally the session cache is checked for expired sessions every
246255 connections using the
247SSL_CTX_flush_sessions(3) function. Since
248this may lead to a delay which cannot be controlled, the automatic
249flushing may be disabled and
250SSL_CTX_flush_sessions(3) can be called
251explicitly by the application.
252.Ip "\s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0" 4
984263bc
MD
253By setting this flag, session-resume operations in an \s-1SSL/TLS\s0 server will not
254automatically look up sessions in the internal cache, even if sessions are
255automatically stored there. If external session caching callbacks are in use,
256this flag guarantees that all lookups are directed to the external cache.
257As automatic lookup only applies for \s-1SSL/TLS\s0 servers, the flag has no effect on
258clients.
259.Ip "\s-1SSL_SESS_CACHE_NO_INTERNAL_STORE\s0" 4
984263bc
MD
260Depending on the presence of \s-1SSL_SESS_CACHE_CLIENT\s0 and/or \s-1SSL_SESS_CACHE_SERVER\s0,
261sessions negotiated in an \s-1SSL/TLS\s0 handshake may be cached for possible reuse.
262Normally a new session is added to the internal cache as well as any external
263session caching (callback) that is configured for the \s-1SSL_CTX\s0. This flag will
264prevent sessions being stored in the internal cache (though the application can
265add them manually using SSL_CTX_add_session(3)). Note:
266in any \s-1SSL/TLS\s0 servers where external caching is configured, any successful
267session lookups in the external cache (ie. for session-resume requests) would
268normally be copied into the local cache before processing continues \- this flag
269prevents these additions to the internal cache as well.
270.Ip "\s-1SSL_SESS_CACHE_NO_INTERNAL\s0" 4
984263bc 271Enable both \s-1SSL_SESS_CACHE_NO_INTERNAL_LOOKUP\s0 and
a7d27d5a 272\s-1SSL_SESS_CACHE_NO_INTERNAL_STORE\s0 at the same time.
984263bc
MD
273.PP
274The default mode is \s-1SSL_SESS_CACHE_SERVER\s0.
275.SH "RETURN VALUES"
a7d27d5a 276\fISSL_CTX_set_session_cache_mode()\fR returns the previously set cache mode.
984263bc 277.PP
a7d27d5a 278\fISSL_CTX_get_session_cache_mode()\fR returns the currently set cache mode.
984263bc 279.SH "SEE ALSO"
984263bc
MD
280ssl(3), SSL_set_session(3),
281SSL_session_reused(3),
282SSL_CTX_add_session(3),
283SSL_CTX_sess_number(3),
284SSL_CTX_sess_set_cache_size(3),
285SSL_CTX_sess_set_get_cb(3),
286SSL_CTX_set_session_id_context(3),
287SSL_CTX_set_timeout(3),
288SSL_CTX_flush_sessions(3)
289.SH "HISTORY"
a7d27d5a 290SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL
984263bc 291were introduced in OpenSSL 0.9.6h.
a7d27d5a
JR
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