Merge branch 'vendor/OPENSSL'
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_info_callback.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
e056f0e0 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
e056f0e0 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
e056f0e0 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
e056f0e0
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
e056f0e0 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
e056f0e0
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
e056f0e0
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
e056f0e0
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
e056f0e0
JR
59. nr % 0
60. rr F
984263bc 61.\}
e056f0e0 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
e056f0e0
JR
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
e056f0e0
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
e056f0e0
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
e056f0e0 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
e056f0e0
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
e056f0e0
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
e056f0e0 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
e056f0e0
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
e056f0e0
JR
129.\" ========================================================================
130.\"
131.IX Title "SSL_CTX_set_info_callback 3"
18ed9402 132.TH SSL_CTX_set_info_callback 3 "2008-09-27" "0.9.8i" "OpenSSL"
984263bc 133.SH "NAME"
a7d27d5a 134SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback \- handle information callback for SSL connections
984263bc 135.SH "SYNOPSIS"
e056f0e0 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/ssl.h>
aac4ff6f
PA
139.Ve
140.PP
141.Vb 2
984263bc 142\& void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
a561f9ff 143\& void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
aac4ff6f
PA
144.Ve
145.PP
146.Vb 2
984263bc 147\& void SSL_set_info_callback(SSL *ssl, void (*callback)());
a561f9ff 148\& void (*SSL_get_info_callback(const SSL *ssl))();
984263bc
MD
149.Ve
150.SH "DESCRIPTION"
e056f0e0
JR
151.IX Header "DESCRIPTION"
152\&\fISSL_CTX_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to
153obtain state information for \s-1SSL\s0 objects created from \fBctx\fR during connection
984263bc 154setup and use. The setting for \fBctx\fR is overridden from the setting for
e056f0e0
JR
155a specific \s-1SSL\s0 object, if specified.
156When \fBcallback\fR is \s-1NULL\s0, not callback function is used.
984263bc 157.PP
e056f0e0 158\&\fISSL_set_info_callback()\fR sets the \fBcallback\fR function, that can be used to
984263bc 159obtain state information for \fBssl\fR during connection setup and use.
e056f0e0
JR
160When \fBcallback\fR is \s-1NULL\s0, the callback setting currently valid for
161\&\fBctx\fR is used.
984263bc 162.PP
e056f0e0 163\&\fISSL_CTX_get_info_callback()\fR returns a pointer to the currently set information
984263bc
MD
164callback function for \fBctx\fR.
165.PP
e056f0e0 166\&\fISSL_get_info_callback()\fR returns a pointer to the currently set information
984263bc
MD
167callback function for \fBssl\fR.
168.SH "NOTES"
e056f0e0 169.IX Header "NOTES"
984263bc 170When setting up a connection and during use, it is possible to obtain state
e056f0e0 171information from the \s-1SSL/TLS\s0 engine. When set, an information callback function
984263bc
MD
172is called whenever the state changes, an alert appears, or an error occurs.
173.PP
e056f0e0 174The callback function is called as \fBcallback(\s-1SSL\s0 *ssl, int where, int ret)\fR.
984263bc
MD
175The \fBwhere\fR argument specifies information about where (in which context)
176the callback function was called. If \fBret\fR is 0, an error condition occurred.
e056f0e0 177If an alert is handled, \s-1SSL_CB_ALERT\s0 is set and \fBret\fR specifies the alert
984263bc
MD
178information.
179.PP
e056f0e0
JR
180\&\fBwhere\fR is a bitmask made up of the following bits:
181.IP "\s-1SSL_CB_LOOP\s0" 4
182.IX Item "SSL_CB_LOOP"
984263bc 183Callback has been called to indicate state change inside a loop.
e056f0e0
JR
184.IP "\s-1SSL_CB_EXIT\s0" 4
185.IX Item "SSL_CB_EXIT"
984263bc
MD
186Callback has been called to indicate error exit of a handshake function.
187(May be soft error with retry option for non-blocking setups.)
e056f0e0
JR
188.IP "\s-1SSL_CB_READ\s0" 4
189.IX Item "SSL_CB_READ"
984263bc 190Callback has been called during read operation.
e056f0e0
JR
191.IP "\s-1SSL_CB_WRITE\s0" 4
192.IX Item "SSL_CB_WRITE"
984263bc 193Callback has been called during write operation.
e056f0e0
JR
194.IP "\s-1SSL_CB_ALERT\s0" 4
195.IX Item "SSL_CB_ALERT"
984263bc 196Callback has been called due to an alert being sent or received.
e056f0e0
JR
197.IP "\s-1SSL_CB_READ_ALERT\s0 (SSL_CB_ALERT|SSL_CB_READ)" 4
198.IX Item "SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ)"
199.PD 0
200.IP "\s-1SSL_CB_WRITE_ALERT\s0 (SSL_CB_ALERT|SSL_CB_WRITE)" 4
201.IX Item "SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE)"
202.IP "\s-1SSL_CB_ACCEPT_LOOP\s0 (SSL_ST_ACCEPT|SSL_CB_LOOP)" 4
203.IX Item "SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP)"
204.IP "\s-1SSL_CB_ACCEPT_EXIT\s0 (SSL_ST_ACCEPT|SSL_CB_EXIT)" 4
205.IX Item "SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT)"
206.IP "\s-1SSL_CB_CONNECT_LOOP\s0 (SSL_ST_CONNECT|SSL_CB_LOOP)" 4
207.IX Item "SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP)"
208.IP "\s-1SSL_CB_CONNECT_EXIT\s0 (SSL_ST_CONNECT|SSL_CB_EXIT)" 4
209.IX Item "SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT)"
210.IP "\s-1SSL_CB_HANDSHAKE_START\s0" 4
211.IX Item "SSL_CB_HANDSHAKE_START"
212.PD
984263bc 213Callback has been called because a new handshake is started.
e056f0e0
JR
214.IP "\s-1SSL_CB_HANDSHAKE_DONE\s0 0x20" 4
215.IX Item "SSL_CB_HANDSHAKE_DONE 0x20"
984263bc
MD
216Callback has been called because a handshake is finished.
217.PP
218The current state information can be obtained using the
e056f0e0 219\&\fISSL_state_string\fR\|(3) family of functions.
984263bc
MD
220.PP
221The \fBret\fR information can be evaluated using the
e056f0e0 222\&\fISSL_alert_type_string\fR\|(3) family of functions.
984263bc 223.SH "RETURN VALUES"
e056f0e0
JR
224.IX Header "RETURN VALUES"
225\&\fISSL_set_info_callback()\fR does not provide diagnostic information.
984263bc 226.PP
e056f0e0 227\&\fISSL_get_info_callback()\fR returns the current setting.
984263bc 228.SH "EXAMPLES"
e056f0e0 229.IX Header "EXAMPLES"
984263bc 230The following example callback function prints state strings, information
e056f0e0 231about alerts being handled and error messages to the \fBbio_err\fR \s-1BIO\s0.
984263bc
MD
232.PP
233.Vb 4
234\& void apps_ssl_info_callback(SSL *s, int where, int ret)
235\& {
236\& const char *str;
237\& int w;
aac4ff6f
PA
238.Ve
239.PP
240.Vb 1
984263bc 241\& w=where& ~SSL_ST_MASK;
aac4ff6f
PA
242.Ve
243.PP
244.Vb 3
984263bc
MD
245\& if (w & SSL_ST_CONNECT) str="SSL_connect";
246\& else if (w & SSL_ST_ACCEPT) str="SSL_accept";
247\& else str="undefined";
aac4ff6f
PA
248.Ve
249.PP
250.Vb 24
984263bc
MD
251\& if (where & SSL_CB_LOOP)
252\& {
253\& BIO_printf(bio_err,"%s:%s\en",str,SSL_state_string_long(s));
254\& }
255\& else if (where & SSL_CB_ALERT)
256\& {
257\& str=(where & SSL_CB_READ)?"read":"write";
258\& BIO_printf(bio_err,"SSL3 alert %s:%s:%s\en",
259\& str,
260\& SSL_alert_type_string_long(ret),
261\& SSL_alert_desc_string_long(ret));
262\& }
263\& else if (where & SSL_CB_EXIT)
264\& {
265\& if (ret == 0)
266\& BIO_printf(bio_err,"%s:failed in %s\en",
267\& str,SSL_state_string_long(s));
268\& else if (ret < 0)
269\& {
270\& BIO_printf(bio_err,"%s:error in %s\en",
271\& str,SSL_state_string_long(s));
272\& }
273\& }
274\& }
275.Ve
276.SH "SEE ALSO"
a7d27d5a 277.IX Header "SEE ALSO"
e056f0e0
JR
278\&\fIssl\fR\|(3), \fISSL_state_string\fR\|(3),
279\&\fISSL_alert_type_string\fR\|(3)