1=pod
2
3=head1 NAME
4
5SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections
6
7=head1 SYNOPSIS
8
9 #include <openssl/ssl.h>
10
11 void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
12 void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
13
14 void SSL_set_info_callback(SSL *ssl, void (*callback)());
15 void (*SSL_get_info_callback(const SSL *ssl))();
16
17=head1 DESCRIPTION
18
19SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
20obtain state information for SSL objects created from B<ctx> during connection
21setup and use. The setting for B<ctx> is overridden from the setting for
22a specific SSL object, if specified.
23When B<callback> is NULL, not callback function is used.
24
25SSL_set_info_callback() sets the B<callback> function, that can be used to
26obtain state information for B<ssl> during connection setup and use.
27When B<callback> is NULL, the callback setting currently valid for
28B<ctx> is used.
29
30SSL_CTX_get_info_callback() returns a pointer to the currently set information
31callback function for B<ctx>.
32
33SSL_get_info_callback() returns a pointer to the currently set information
34callback function for B<ssl>.
35
36=head1 NOTES
37
38When setting up a connection and during use, it is possible to obtain state
39information from the SSL/TLS engine. When set, an information callback function
40is called whenever the state changes, an alert appears, or an error occurs.
41
42The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
43The B<where> argument specifies information about where (in which context)
44the callback function was called. If B<ret> is 0, an error condition occurred.
45If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
46information.
47
48B<where> is a bitmask made up of the following bits:
49
50=over 4
51
52=item SSL_CB_LOOP
53
54Callback has been called to indicate state change inside a loop.
55
56=item SSL_CB_EXIT
57
58Callback has been called to indicate error exit of a handshake function.
59(May be soft error with retry option for non-blocking setups.)
60
61=item SSL_CB_READ
62
63Callback has been called during read operation.
64
65=item SSL_CB_WRITE
66
67Callback has been called during write operation.
68
69=item SSL_CB_ALERT
70
71Callback has been called due to an alert being sent or received.
72
73=item SSL_CB_READ_ALERT               (SSL_CB_ALERT|SSL_CB_READ)
74
75=item SSL_CB_WRITE_ALERT              (SSL_CB_ALERT|SSL_CB_WRITE)
76
77=item SSL_CB_ACCEPT_LOOP              (SSL_ST_ACCEPT|SSL_CB_LOOP)
78
79=item SSL_CB_ACCEPT_EXIT              (SSL_ST_ACCEPT|SSL_CB_EXIT)
80
81=item SSL_CB_CONNECT_LOOP             (SSL_ST_CONNECT|SSL_CB_LOOP)
82
83=item SSL_CB_CONNECT_EXIT             (SSL_ST_CONNECT|SSL_CB_EXIT)
84
85=item SSL_CB_HANDSHAKE_START
86
87Callback has been called because a new handshake is started.
88
89=item SSL_CB_HANDSHAKE_DONE           0x20
90
91Callback has been called because a handshake is finished.
92
93=back
94
95The current state information can be obtained using the
96L<SSL_state_string(3)|SSL_state_string(3)> family of functions.
97
98The B<ret> information can be evaluated using the
99L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> family of functions.
100
101=head1 RETURN VALUES
102
103SSL_set_info_callback() does not provide diagnostic information.
104
105SSL_get_info_callback() returns the current setting.
106
107=head1 EXAMPLES
108
109The following example callback function prints state strings, information
110about alerts being handled and error messages to the B<bio_err> BIO.
111
112 void apps_ssl_info_callback(SSL *s, int where, int ret)
113	{
114	const char *str;
115	int w;
116
117	w=where& ~SSL_ST_MASK;
118
119	if (w & SSL_ST_CONNECT) str="SSL_connect";
120	else if (w & SSL_ST_ACCEPT) str="SSL_accept";
121	else str="undefined";
122
123	if (where & SSL_CB_LOOP)
124		{
125		BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s));
126		}
127	else if (where & SSL_CB_ALERT)
128		{
129		str=(where & SSL_CB_READ)?"read":"write";
130		BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n",
131			str,
132			SSL_alert_type_string_long(ret),
133			SSL_alert_desc_string_long(ret));
134		}
135	else if (where & SSL_CB_EXIT)
136		{
137		if (ret == 0)
138			BIO_printf(bio_err,"%s:failed in %s\n",
139				str,SSL_state_string_long(s));
140		else if (ret < 0)
141			{
142			BIO_printf(bio_err,"%s:error in %s\n",
143				str,SSL_state_string_long(s));
144			}
145		}
146	}
147
148=head1 SEE ALSO
149
150L<ssl(3)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>,
151L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>
152
153=cut
154