Update per latest manual pages after running 'man-update'.
[dragonfly.git] / 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