Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_info_callback.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_info_callback 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_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback \- handle information callback for SSL connections
192 .SH "SYNOPSIS"
193 .PP
194 .Vb 1
195 \& #include <openssl/ssl.h>
196 .Ve
197 .Vb 2
198 \& void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
199 \& void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))();
200 .Ve
201 .Vb 2
202 \& void SSL_set_info_callback(SSL *ssl, void (*callback)());
203 \& void (*SSL_get_info_callback(SSL *ssl))();
204 .Ve
205 .SH "DESCRIPTION"
206 \fISSL_CTX_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to
207 obtain state information for SSL objects created from \fBctx\fR during connection
208 setup and use. The setting for \fBctx\fR is overridden from the setting for
209 a specific SSL object, if specified.
210 When \fBcallback\fR is NULL, not callback function is used.
211 .PP
212 \fISSL_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to
213 obtain state information for \fBssl\fR during connection setup and use.
214 When \fBcallback\fR is NULL, the callback setting currently valid for
215 \fBctx\fR is used.
216 .PP
217 \fISSL_CTX_get_info_callback()\fR returns a pointer to the currently set information
218 callback function for \fBctx\fR.
219 .PP
220 \fISSL_get_info_callback()\fR returns a pointer to the currently set information
221 callback function for \fBssl\fR.
222 .SH "NOTES"
223 When setting up a connection and during use, it is possible to obtain state
224 information from the SSL/TLS engine. When set, an information callback function
225 is called whenever the state changes, an alert appears, or an error occurs.
226 .PP
227 The callback function is called as \fBcallback(SSL *ssl, int where, int ret)\fR.
228 The \fBwhere\fR argument specifies information about where (in which context)
229 the callback function was called. If \fBret\fR is 0, an error condition occurred.
230 If an alert is handled, SSL_CB_ALERT is set and \fBret\fR specifies the alert
231 information.
232 .PP
233 \fBwhere\fR is a bitmask made up of the following bits:
234 .Ip "\s-1SSL_CB_LOOP\s0" 4
235 Callback has been called to indicate state change inside a loop.
236 .Ip "\s-1SSL_CB_EXIT\s0" 4
237 Callback has been called to indicate error exit of a handshake function.
238 (May be soft error with retry option for non-blocking setups.)
239 .Ip "\s-1SSL_CB_READ\s0" 4
240 Callback has been called during read operation.
241 .Ip "\s-1SSL_CB_WRITE\s0" 4
242 Callback has been called during write operation.
243 .Ip "\s-1SSL_CB_ALERT\s0" 4
244 Callback has been called due to an alert being sent or received.
245 .Ip "\s-1SSL_CB_READ_ALERT\s0               (\s-1SSL_CB_ALERT\s0|\s-1SSL_CB_READ\s0)" 4
246 .Ip "\s-1SSL_CB_WRITE_ALERT\s0              (\s-1SSL_CB_ALERT\s0|\s-1SSL_CB_WRITE\s0)" 4
247 .Ip "\s-1SSL_CB_ACCEPT_LOOP\s0              (\s-1SSL_ST_ACCEPT\s0|\s-1SSL_CB_LOOP\s0)" 4
248 .Ip "\s-1SSL_CB_ACCEPT_EXIT\s0              (\s-1SSL_ST_ACCEPT\s0|\s-1SSL_CB_EXIT\s0)" 4
249 .Ip "\s-1SSL_CB_CONNECT_LOOP\s0             (\s-1SSL_ST_CONNECT\s0|\s-1SSL_CB_LOOP\s0)" 4
250 .Ip "\s-1SSL_CB_CONNECT_EXIT\s0             (\s-1SSL_ST_CONNECT\s0|\s-1SSL_CB_EXIT\s0)" 4
251 .Ip "\s-1SSL_CB_HANDSHAKE_START\s0" 4
252 Callback has been called because a new handshake is started.
253 .Ip "\s-1SSL_CB_HANDSHAKE_DONE\s0           0x20" 4
254 Callback has been called because a handshake is finished.
255 .PP
256 The current state information can be obtained using the
257 SSL_state_string(3) family of functions.
258 .PP
259 The \fBret\fR information can be evaluated using the
260 SSL_alert_type_string(3) family of functions.
261 .SH "RETURN VALUES"
262 \fISSL_set_info_callback()\fR does not provide diagnostic information.
263 .PP
264 \fISSL_get_info_callback()\fR returns the current setting.
265 .SH "EXAMPLES"
266 The following example callback function prints state strings, information
267 about alerts being handled and error messages to the \fBbio_err\fR BIO.
268 .PP
269 .Vb 4
270 \& void apps_ssl_info_callback(SSL *s, int where, int ret)
271 \&        {
272 \&        const char *str;
273 \&        int w;
274 .Ve
275 .Vb 1
276 \&        w=where& ~SSL_ST_MASK;
277 .Ve
278 .Vb 3
279 \&        if (w & SSL_ST_CONNECT) str="SSL_connect";
280 \&        else if (w & SSL_ST_ACCEPT) str="SSL_accept";
281 \&        else str="undefined";
282 .Ve
283 .Vb 24
284 \&        if (where & SSL_CB_LOOP)
285 \&                {
286 \&                BIO_printf(bio_err,"%s:%s\en",str,SSL_state_string_long(s));
287 \&                }
288 \&        else if (where & SSL_CB_ALERT)
289 \&                {
290 \&                str=(where & SSL_CB_READ)?"read":"write";
291 \&                BIO_printf(bio_err,"SSL3 alert %s:%s:%s\en",
292 \&                        str,
293 \&                        SSL_alert_type_string_long(ret),
294 \&                        SSL_alert_desc_string_long(ret));
295 \&                }
296 \&        else if (where & SSL_CB_EXIT)
297 \&                {
298 \&                if (ret == 0)
299 \&                        BIO_printf(bio_err,"%s:failed in %s\en",
300 \&                                str,SSL_state_string_long(s));
301 \&                else if (ret < 0)
302 \&                        {
303 \&                        BIO_printf(bio_err,"%s:error in %s\en",
304 \&                                str,SSL_state_string_long(s));
305 \&                        }
306 \&                }
307 \&        }
308 .Ve
309 .SH "SEE ALSO"
310 ssl(3), SSL_state_string(3),
311 SSL_alert_type_string(3)
312
313 .rn }` ''
314 .IX Title "SSL_CTX_set_info_callback 3"
315 .IX Name "SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections"
316
317 .IX Header "NAME"
318
319 .IX Header "SYNOPSIS"
320
321 .IX Header "DESCRIPTION"
322
323 .IX Header "NOTES"
324
325 .IX Item "\s-1SSL_CB_LOOP\s0"
326
327 .IX Item "\s-1SSL_CB_EXIT\s0"
328
329 .IX Item "\s-1SSL_CB_READ\s0"
330
331 .IX Item "\s-1SSL_CB_WRITE\s0"
332
333 .IX Item "\s-1SSL_CB_ALERT\s0"
334
335 .IX Item "\s-1SSL_CB_READ_ALERT\s0               (\s-1SSL_CB_ALERT\s0|\s-1SSL_CB_READ\s0)"
336
337 .IX Item "\s-1SSL_CB_WRITE_ALERT\s0              (\s-1SSL_CB_ALERT\s0|\s-1SSL_CB_WRITE\s0)"
338
339 .IX Item "\s-1SSL_CB_ACCEPT_LOOP\s0              (\s-1SSL_ST_ACCEPT\s0|\s-1SSL_CB_LOOP\s0)"
340
341 .IX Item "\s-1SSL_CB_ACCEPT_EXIT\s0              (\s-1SSL_ST_ACCEPT\s0|\s-1SSL_CB_EXIT\s0)"
342
343 .IX Item "\s-1SSL_CB_CONNECT_LOOP\s0             (\s-1SSL_ST_CONNECT\s0|\s-1SSL_CB_LOOP\s0)"
344
345 .IX Item "\s-1SSL_CB_CONNECT_EXIT\s0             (\s-1SSL_ST_CONNECT\s0|\s-1SSL_CB_EXIT\s0)"
346
347 .IX Item "\s-1SSL_CB_HANDSHAKE_START\s0"
348
349 .IX Item "\s-1SSL_CB_HANDSHAKE_DONE\s0           0x20"
350
351 .IX Header "RETURN VALUES"
352
353 .IX Header "EXAMPLES"
354
355 .IX Header "SEE ALSO"
356