Remove my local patch again, it was still not meant to be commited.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_sess_set_get_cb.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_sess_set_get_cb 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_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"
a7d27d5a 193.PP
984263bc
MD
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"
a7d27d5a 217\fISSL_CTX_sess_set_new_cb()\fR sets the callback function, which is automatically
984263bc
MD
218called whenever a new session was negotiated.
219.PP
a7d27d5a
JR
220\fISSL_CTX_sess_set_remove_cb()\fR sets the callback function, which is
221automatically called whenever a session is removed by the SSL engine,
984263bc
MD
222because it is considered faulty or the session has become obsolete because
223of exceeding the timeout value.
224.PP
a7d27d5a
JR
225\fISSL_CTX_sess_set_get_cb()\fR sets the callback function which is called,
226whenever a SSL/TLS client proposed to resume a session but the session
984263bc
MD
227could not be found in the internal session cache (see
228SSL_CTX_set_session_cache_mode(3)).
a7d27d5a 229(SSL/TLS server only.)
984263bc 230.PP
a7d27d5a
JR
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
984263bc 233provided callback functions. If a callback function has not been set,
a7d27d5a 234the NULL pointer is returned.
984263bc 235.SH "NOTES"
984263bc
MD
236In order to allow external session caching, synchronization with the internal
237session cache is realized via callback functions. Inside these callback
238functions, session can be saved to disk or put into a database using the
239d2i_SSL_SESSION(3) interface.
240.PP
241The \fInew_session_cb()\fR is called, whenever a new session has been negotiated
242and session caching is enabled (see
243SSL_CTX_set_session_cache_mode(3)).
244The \fInew_session_cb()\fR is passed the \fBssl\fR connection and the ssl session
a7d27d5a 245\fBsess\fR. If the callback returns \fB0\fR, the session will be immediately
984263bc
MD
246removed again.
247.PP
a7d27d5a
JR
248The \fIremove_session_cb()\fR is called, whenever the SSL engine removes a session
249from the internal cache. This happens when the session is removed because
250it is expired or when a connection was not shutdown cleanly. It also happens
251for all sessions in the internal session cache when
252SSL_CTX_free(3) is called. The \fIremove_session_cb()\fR is passed
253the \fBctx\fR and the ssl session \fBsess\fR. It does not provide any feedback.
984263bc 254.PP
a7d27d5a 255The \fIget_session_cb()\fR is only called on SSL/TLS servers with the session id
984263bc
MD
256proposed by the client. The \fIget_session_cb()\fR is always called, also when
257session caching was disabled. The \fIget_session_cb()\fR is passed the
a7d27d5a
JR
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
260SSL engine to increment the reference count of the SSL_SESSION object,
984263bc
MD
261Normally the reference count is not incremented and therefore the
262session must not be explicitly freed with
263SSL_SESSION_free(3).
264.SH "SEE ALSO"
984263bc
MD
265ssl(3), d2i_SSL_SESSION(3),
266SSL_CTX_set_session_cache_mode(3),
267SSL_CTX_flush_sessions(3),
a7d27d5a
JR
268SSL_SESSION_free(3),
269SSL_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