Remove my local patch again, it was still not meant to be commited.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_info_callback.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_info_callback 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 190.SH "NAME"
a7d27d5a 191SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback \- handle information callback for SSL connections
984263bc 192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
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"
a7d27d5a
JR
206\fISSL_CTX_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to
207obtain state information for SSL objects created from \fBctx\fR during connection
984263bc 208setup and use. The setting for \fBctx\fR is overridden from the setting for
a7d27d5a
JR
209a specific SSL object, if specified.
210When \fBcallback\fR is NULL, not callback function is used.
984263bc 211.PP
a7d27d5a 212\fISSL_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to
984263bc 213obtain state information for \fBssl\fR during connection setup and use.
a7d27d5a
JR
214When \fBcallback\fR is NULL, the callback setting currently valid for
215\fBctx\fR is used.
984263bc 216.PP
a7d27d5a 217\fISSL_CTX_get_info_callback()\fR returns a pointer to the currently set information
984263bc
MD
218callback function for \fBctx\fR.
219.PP
a7d27d5a 220\fISSL_get_info_callback()\fR returns a pointer to the currently set information
984263bc
MD
221callback function for \fBssl\fR.
222.SH "NOTES"
984263bc 223When setting up a connection and during use, it is possible to obtain state
a7d27d5a 224information from the SSL/TLS engine. When set, an information callback function
984263bc
MD
225is called whenever the state changes, an alert appears, or an error occurs.
226.PP
a7d27d5a 227The callback function is called as \fBcallback(SSL *ssl, int where, int ret)\fR.
984263bc
MD
228The \fBwhere\fR argument specifies information about where (in which context)
229the callback function was called. If \fBret\fR is 0, an error condition occurred.
a7d27d5a 230If an alert is handled, SSL_CB_ALERT is set and \fBret\fR specifies the alert
984263bc
MD
231information.
232.PP
a7d27d5a 233\fBwhere\fR is a bitmask made up of the following bits:
984263bc 234.Ip "\s-1SSL_CB_LOOP\s0" 4
984263bc
MD
235Callback has been called to indicate state change inside a loop.
236.Ip "\s-1SSL_CB_EXIT\s0" 4
984263bc
MD
237Callback 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
984263bc
MD
240Callback has been called during read operation.
241.Ip "\s-1SSL_CB_WRITE\s0" 4
984263bc
MD
242Callback has been called during write operation.
243.Ip "\s-1SSL_CB_ALERT\s0" 4
984263bc 244Callback has been called due to an alert being sent or received.
a7d27d5a
JR
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
984263bc 251.Ip "\s-1SSL_CB_HANDSHAKE_START\s0" 4
984263bc
MD
252Callback has been called because a new handshake is started.
253.Ip "\s-1SSL_CB_HANDSHAKE_DONE\s0 0x20" 4
984263bc
MD
254Callback has been called because a handshake is finished.
255.PP
256The current state information can be obtained using the
257SSL_state_string(3) family of functions.
258.PP
259The \fBret\fR information can be evaluated using the
260SSL_alert_type_string(3) family of functions.
261.SH "RETURN VALUES"
a7d27d5a 262\fISSL_set_info_callback()\fR does not provide diagnostic information.
984263bc 263.PP
a7d27d5a 264\fISSL_get_info_callback()\fR returns the current setting.
984263bc 265.SH "EXAMPLES"
984263bc 266The following example callback function prints state strings, information
a7d27d5a 267about alerts being handled and error messages to the \fBbio_err\fR BIO.
984263bc
MD
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"
984263bc
MD
310ssl(3), SSL_state_string(3),
311SSL_alert_type_string(3)
a7d27d5a
JR
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