2 ''' $RCSfile$$Revision$$Date$
20 .ie \\n(.$>=3 .ne \\$3
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.
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
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
80 .\" If the F register is turned on, we'll generate
81 .\" index entries out stderr for the following things:
86 .\" X<> Xref (embedded
87 .\" Of course, you have to process the output yourself
88 .\" in some meaninful fashion.
91 .tm Index:\\$1\t\\n%\t"\\$2"
96 .TH SSL_CTX_set_info_callback 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
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
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 . \" AM - accent mark definitions
113 . \" fudge factors for nroff and troff
122 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
128 . \" simple accents for nroff and troff
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'
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 \
175 . ds v \h'-1'\o'\(aa\(ga'
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
195 \& #include <openssl/ssl.h>
198 \& void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
199 \& void (*SSL_CTX_get_info_callback(SSL_CTX *ctx))();
202 \& void SSL_set_info_callback(SSL *ssl, void (*callback)());
203 \& void (*SSL_get_info_callback(SSL *ssl))();
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.
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
217 \fISSL_CTX_get_info_callback()\fR returns a pointer to the currently set information
218 callback function for \fBctx\fR.
220 \fISSL_get_info_callback()\fR returns a pointer to the currently set information
221 callback function for \fBssl\fR.
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.
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
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.
256 The current state information can be obtained using the
257 SSL_state_string(3) family of functions.
259 The \fBret\fR information can be evaluated using the
260 SSL_alert_type_string(3) family of functions.
262 \fISSL_set_info_callback()\fR does not provide diagnostic information.
264 \fISSL_get_info_callback()\fR returns the current setting.
266 The following example callback function prints state strings, information
267 about alerts being handled and error messages to the \fBbio_err\fR BIO.
270 \& void apps_ssl_info_callback(SSL *s, int where, int ret)
276 \& w=where& ~SSL_ST_MASK;
279 \& if (w & SSL_ST_CONNECT) str="SSL_connect";
280 \& else if (w & SSL_ST_ACCEPT) str="SSL_accept";
281 \& else str="undefined";
284 \& if (where & SSL_CB_LOOP)
286 \& BIO_printf(bio_err,"%s:%s\en",str,SSL_state_string_long(s));
288 \& else if (where & SSL_CB_ALERT)
290 \& str=(where & SSL_CB_READ)?"read":"write";
291 \& BIO_printf(bio_err,"SSL3 alert %s:%s:%s\en",
293 \& SSL_alert_type_string_long(ret),
294 \& SSL_alert_desc_string_long(ret));
296 \& else if (where & SSL_CB_EXIT)
299 \& BIO_printf(bio_err,"%s:failed in %s\en",
300 \& str,SSL_state_string_long(s));
303 \& BIO_printf(bio_err,"%s:error in %s\en",
304 \& str,SSL_state_string_long(s));
310 ssl(3), SSL_state_string(3),
311 SSL_alert_type_string(3)
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"
319 .IX Header "SYNOPSIS"
321 .IX Header "DESCRIPTION"
325 .IX Item "\s-1SSL_CB_LOOP\s0"
327 .IX Item "\s-1SSL_CB_EXIT\s0"
329 .IX Item "\s-1SSL_CB_READ\s0"
331 .IX Item "\s-1SSL_CB_WRITE\s0"
333 .IX Item "\s-1SSL_CB_ALERT\s0"
335 .IX Item "\s-1SSL_CB_READ_ALERT\s0 (\s-1SSL_CB_ALERT\s0|\s-1SSL_CB_READ\s0)"
337 .IX Item "\s-1SSL_CB_WRITE_ALERT\s0 (\s-1SSL_CB_ALERT\s0|\s-1SSL_CB_WRITE\s0)"
339 .IX Item "\s-1SSL_CB_ACCEPT_LOOP\s0 (\s-1SSL_ST_ACCEPT\s0|\s-1SSL_CB_LOOP\s0)"
341 .IX Item "\s-1SSL_CB_ACCEPT_EXIT\s0 (\s-1SSL_ST_ACCEPT\s0|\s-1SSL_CB_EXIT\s0)"
343 .IX Item "\s-1SSL_CB_CONNECT_LOOP\s0 (\s-1SSL_ST_CONNECT\s0|\s-1SSL_CB_LOOP\s0)"
345 .IX Item "\s-1SSL_CB_CONNECT_EXIT\s0 (\s-1SSL_ST_CONNECT\s0|\s-1SSL_CB_EXIT\s0)"
347 .IX Item "\s-1SSL_CB_HANDSHAKE_START\s0"
349 .IX Item "\s-1SSL_CB_HANDSHAKE_DONE\s0 0x20"
351 .IX Header "RETURN VALUES"
353 .IX Header "EXAMPLES"
355 .IX Header "SEE ALSO"