]>
Commit | Line | Data |
---|---|---|
f1b28074 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5bbf42a5 MC |
5 | SSL_CTX_set_info_callback, |
6 | SSL_CTX_get_info_callback, | |
7 | SSL_set_info_callback, | |
8 | SSL_get_info_callback | |
9 | - handle information callback for SSL connections | |
f1b28074 LJ |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/ssl.h> | |
14 | ||
15 | void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); | |
c3e64028 | 16 | void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); |
f1b28074 LJ |
17 | |
18 | void SSL_set_info_callback(SSL *ssl, void (*callback)()); | |
c3e64028 | 19 | void (*SSL_get_info_callback(const SSL *ssl))(); |
f1b28074 | 20 | |
f1b28074 LJ |
21 | =head1 DESCRIPTION |
22 | ||
23 | SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to | |
24 | obtain state information for SSL objects created from B<ctx> during connection | |
25 | setup and use. The setting for B<ctx> is overridden from the setting for | |
26 | a specific SSL object, if specified. | |
d7003c4d | 27 | When B<callback> is NULL, no callback function is used. |
f1b28074 LJ |
28 | |
29 | SSL_set_info_callback() sets the B<callback> function, that can be used to | |
30 | obtain state information for B<ssl> during connection setup and use. | |
31 | When B<callback> is NULL, the callback setting currently valid for | |
32 | B<ctx> is used. | |
33 | ||
34 | SSL_CTX_get_info_callback() returns a pointer to the currently set information | |
35 | callback function for B<ctx>. | |
36 | ||
37 | SSL_get_info_callback() returns a pointer to the currently set information | |
38 | callback function for B<ssl>. | |
39 | ||
40 | =head1 NOTES | |
41 | ||
42 | When setting up a connection and during use, it is possible to obtain state | |
43 | information from the SSL/TLS engine. When set, an information callback function | |
5bbf42a5 MC |
44 | is called whenever a significant event occurs such as: the state changes, |
45 | an alert appears, or an error occurs. | |
f1b28074 LJ |
46 | |
47 | The callback function is called as B<callback(SSL *ssl, int where, int ret)>. | |
48 | The B<where> argument specifies information about where (in which context) | |
3b80e3aa | 49 | the callback function was called. If B<ret> is 0, an error condition occurred. |
f1b28074 LJ |
50 | If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert |
51 | information. | |
52 | ||
9c0586d5 | 53 | B<where> is a bit-mask made up of the following bits: |
f1b28074 LJ |
54 | |
55 | =over 4 | |
56 | ||
57 | =item SSL_CB_LOOP | |
58 | ||
5bbf42a5 MC |
59 | Callback has been called to indicate state change or some other significant |
60 | state machine event. This may mean that the callback gets invoked more than once | |
61 | per state in some situations. | |
f1b28074 LJ |
62 | |
63 | =item SSL_CB_EXIT | |
64 | ||
5bbf42a5 MC |
65 | Callback has been called to indicate exit of a handshake function. This will |
66 | happen after the end of a handshake, but may happen at other times too such as | |
490c8711 | 67 | on error or when IO might otherwise block and nonblocking is being used. |
f1b28074 LJ |
68 | |
69 | =item SSL_CB_READ | |
70 | ||
71 | Callback has been called during read operation. | |
72 | ||
73 | =item SSL_CB_WRITE | |
74 | ||
75 | Callback has been called during write operation. | |
76 | ||
77 | =item SSL_CB_ALERT | |
78 | ||
79 | Callback has been called due to an alert being sent or received. | |
80 | ||
81 | =item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) | |
82 | ||
83 | =item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) | |
84 | ||
85 | =item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) | |
86 | ||
87 | =item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) | |
88 | ||
89 | =item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) | |
90 | ||
91 | =item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) | |
92 | ||
93 | =item SSL_CB_HANDSHAKE_START | |
94 | ||
4af5836b MC |
95 | Callback has been called because a new handshake is started. It also occurs when |
96 | resuming a handshake following a pause to handle early data. | |
f1b28074 | 97 | |
4af5836b | 98 | =item SSL_CB_HANDSHAKE_DONE |
f1b28074 | 99 | |
4af5836b MC |
100 | Callback has been called because a handshake is finished. It also occurs if the |
101 | handshake is paused to allow the exchange of early data. | |
f1b28074 LJ |
102 | |
103 | =back | |
104 | ||
105 | The current state information can be obtained using the | |
9b86974e | 106 | L<SSL_state_string(3)> family of functions. |
f1b28074 LJ |
107 | |
108 | The B<ret> information can be evaluated using the | |
9b86974e | 109 | L<SSL_alert_type_string(3)> family of functions. |
f1b28074 LJ |
110 | |
111 | =head1 RETURN VALUES | |
112 | ||
113 | SSL_set_info_callback() does not provide diagnostic information. | |
114 | ||
115 | SSL_get_info_callback() returns the current setting. | |
116 | ||
117 | =head1 EXAMPLES | |
118 | ||
119 | The following example callback function prints state strings, information | |
120 | about alerts being handled and error messages to the B<bio_err> BIO. | |
121 | ||
122 | void apps_ssl_info_callback(SSL *s, int where, int ret) | |
2947af32 BB |
123 | { |
124 | const char *str; | |
125 | int w = where & ~SSL_ST_MASK; | |
126 | ||
127 | if (w & SSL_ST_CONNECT) | |
128 | str = "SSL_connect"; | |
129 | else if (w & SSL_ST_ACCEPT) | |
130 | str = "SSL_accept"; | |
131 | else | |
132 | str = "undefined"; | |
133 | ||
134 | if (where & SSL_CB_LOOP) { | |
135 | BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s)); | |
136 | } else if (where & SSL_CB_ALERT) { | |
137 | str = (where & SSL_CB_READ) ? "read" : "write"; | |
138 | BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n", str, | |
139 | SSL_alert_type_string_long(ret), | |
140 | SSL_alert_desc_string_long(ret)); | |
141 | } else if (where & SSL_CB_EXIT) { | |
142 | if (ret == 0) { | |
143 | BIO_printf(bio_err, "%s:failed in %s\n", | |
144 | str, SSL_state_string_long(s)); | |
145 | } else if (ret < 0) { | |
146 | BIO_printf(bio_err, "%s:error in %s\n", | |
147 | str, SSL_state_string_long(s)); | |
148 | } | |
149 | } | |
150 | } | |
f1b28074 LJ |
151 | |
152 | =head1 SEE ALSO | |
153 | ||
b97fdb57 | 154 | L<ssl(7)>, L<SSL_state_string(3)>, |
9b86974e | 155 | L<SSL_alert_type_string(3)> |
f1b28074 | 156 | |
e2f92610 RS |
157 | =head1 COPYRIGHT |
158 | ||
0f84cbc3 | 159 | Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 160 | |
4746f25a | 161 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
162 | this file except in compliance with the License. You can obtain a copy |
163 | in the file LICENSE in the source distribution or at | |
164 | L<https://www.openssl.org/source/license.html>. | |
165 | ||
166 | =cut |