]>
Commit | Line | Data |
---|---|---|
f1b28074 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_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)()); | |
c3e64028 | 12 | void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); |
f1b28074 LJ |
13 | |
14 | void SSL_set_info_callback(SSL *ssl, void (*callback)()); | |
c3e64028 | 15 | void (*SSL_get_info_callback(const SSL *ssl))(); |
f1b28074 | 16 | |
f1b28074 LJ |
17 | =head1 DESCRIPTION |
18 | ||
19 | SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to | |
20 | obtain state information for SSL objects created from B<ctx> during connection | |
21 | setup and use. The setting for B<ctx> is overridden from the setting for | |
22 | a specific SSL object, if specified. | |
d7003c4d | 23 | When B<callback> is NULL, no callback function is used. |
f1b28074 LJ |
24 | |
25 | SSL_set_info_callback() sets the B<callback> function, that can be used to | |
26 | obtain state information for B<ssl> during connection setup and use. | |
27 | When B<callback> is NULL, the callback setting currently valid for | |
28 | B<ctx> is used. | |
29 | ||
30 | SSL_CTX_get_info_callback() returns a pointer to the currently set information | |
31 | callback function for B<ctx>. | |
32 | ||
33 | SSL_get_info_callback() returns a pointer to the currently set information | |
34 | callback function for B<ssl>. | |
35 | ||
36 | =head1 NOTES | |
37 | ||
38 | When setting up a connection and during use, it is possible to obtain state | |
39 | information from the SSL/TLS engine. When set, an information callback function | |
40 | is called whenever the state changes, an alert appears, or an error occurs. | |
41 | ||
42 | The callback function is called as B<callback(SSL *ssl, int where, int ret)>. | |
43 | The B<where> argument specifies information about where (in which context) | |
3b80e3aa | 44 | the callback function was called. If B<ret> is 0, an error condition occurred. |
f1b28074 LJ |
45 | If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert |
46 | information. | |
47 | ||
48 | B<where> is a bitmask made up of the following bits: | |
49 | ||
50 | =over 4 | |
51 | ||
52 | =item SSL_CB_LOOP | |
53 | ||
54 | Callback has been called to indicate state change inside a loop. | |
55 | ||
56 | =item SSL_CB_EXIT | |
57 | ||
58 | Callback 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 | ||
63 | Callback has been called during read operation. | |
64 | ||
65 | =item SSL_CB_WRITE | |
66 | ||
67 | Callback has been called during write operation. | |
68 | ||
69 | =item SSL_CB_ALERT | |
70 | ||
71 | Callback 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 | ||
87 | Callback has been called because a new handshake is started. | |
88 | ||
89 | =item SSL_CB_HANDSHAKE_DONE 0x20 | |
90 | ||
91 | Callback has been called because a handshake is finished. | |
92 | ||
93 | =back | |
94 | ||
95 | The current state information can be obtained using the | |
9b86974e | 96 | L<SSL_state_string(3)> family of functions. |
f1b28074 LJ |
97 | |
98 | The B<ret> information can be evaluated using the | |
9b86974e | 99 | L<SSL_alert_type_string(3)> family of functions. |
f1b28074 LJ |
100 | |
101 | =head1 RETURN VALUES | |
102 | ||
103 | SSL_set_info_callback() does not provide diagnostic information. | |
104 | ||
105 | SSL_get_info_callback() returns the current setting. | |
106 | ||
107 | =head1 EXAMPLES | |
108 | ||
109 | The following example callback function prints state strings, information | |
110 | about 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 | ||
9b86974e RS |
150 | L<ssl(3)>, L<SSL_state_string(3)>, |
151 | L<SSL_alert_type_string(3)> | |
f1b28074 LJ |
152 | |
153 | =cut |