| blob | 1bb248135f202dc7b546a90c9573d560d1a0bed9 |
1 .\" $OpenBSD: SSL_CTX_set_info_callback.3,v 1.3 2018/03/21 05:07:04 schwarze Exp $
2 .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3 .\"
4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
5 .\" Copyright (c) 2001, 2005, 2014 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: March 21 2018 $
52 .Dt SSL_CTX_SET_INFO_CALLBACK 3
53 .Os
54 .Sh NAME
55 .Nm SSL_CTX_set_info_callback ,
56 .Nm SSL_CTX_get_info_callback ,
57 .Nm SSL_set_info_callback ,
58 .Nm SSL_get_info_callback
59 .Nd handle information callback for SSL connections
60 .Sh SYNOPSIS
61 .In openssl/ssl.h
62 .Ft void
63 .Fo SSL_CTX_set_info_callback
64 .Fa "SSL_CTX *ctx"
65 .Fa "void (*callback)(const SSL *ssl, int where, int ret)"
66 .Fc
67 .Ft void
68 .Fo "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))"
69 .Fa "const SSL *ssl"
70 .Fa "int where"
71 .Fa "int ret"
72 .Fc
73 .Ft void
74 .Fo SSL_set_info_callback
75 .Fa "SSL *ssl"
76 .Fa "void (*callback)(const SSL *ssl, int where, int ret)"
77 .Fc
78 .Ft void
79 .Fo "(*SSL_get_info_callback(const SSL *ssl))"
80 .Fa "const SSL *ssl"
81 .Fa "int where"
82 .Fa "int ret"
83 .Fc
84 .Sh DESCRIPTION
85 .Fn SSL_CTX_set_info_callback
86 sets the
87 .Fa callback
88 function that can be used to obtain state information for SSL objects created
89 from
90 .Fa ctx
91 during connection setup and use.
92 The setting for
93 .Fa ctx
94 is overridden from the setting for a specific SSL object, if specified.
95 When
96 .Fa callback
97 is
98 .Dv NULL ,
99 no callback function is used.
100 .Pp
101 .Fn SSL_set_info_callback
102 sets the
103 .Fa callback
104 function that can be used to
105 obtain state information for
106 .Fa ssl
107 during connection setup and use.
108 When
109 .Fa callback
110 is
111 .Dv NULL ,
112 the callback setting currently valid for
113 .Fa ctx
114 is used.
115 .Pp
116 .Fn SSL_CTX_get_info_callback
117 returns a pointer to the currently set information callback function for
118 .Fa ctx .
119 .Pp
120 .Fn SSL_get_info_callback
121 returns a pointer to the currently set information callback function for
122 .Fa ssl .
123 .Pp
124 When setting up a connection and during use,
125 it is possible to obtain state information from the SSL/TLS engine.
126 When set, an information callback function is called whenever the state changes,
127 an alert appears, or an error occurs.
128 .Pp
129 The callback function is called as
130 .Fn callback "SSL *ssl" "int where" "int ret" .
131 The
132 .Fa where
133 argument specifies information about where (in which context)
134 the callback function was called.
135 If
136 .Fa ret
137 is 0, an error condition occurred.
138 If an alert is handled,
139 .Dv SSL_CB_ALERT
140 is set and
141 .Fa ret
142 specifies the alert information.
143 .Pp
144 .Fa where
145 is a bitmask made up of the following bits:
146 .Bl -tag -width Ds
147 .It Dv SSL_CB_LOOP
148 Callback has been called to indicate state change inside a loop.
149 .It Dv SSL_CB_EXIT
150 Callback has been called to indicate error exit of a handshake function.
151 (May be soft error with retry option for non-blocking setups.)
152 .It Dv SSL_CB_READ
153 Callback has been called during read operation.
154 .It Dv SSL_CB_WRITE
155 Callback has been called during write operation.
156 .It Dv SSL_CB_ALERT
157 Callback has been called due to an alert being sent or received.
158 .It Dv SSL_CB_READ_ALERT
159 .It Dv SSL_CB_WRITE_ALERT
160 .It Dv SSL_CB_ACCEPT_LOOP
161 .It Dv SSL_CB_ACCEPT_EXIT
162 .It Dv SSL_CB_CONNECT_LOOP
163 .It Dv SSL_CB_CONNECT_EXIT
164 .It Dv SSL_CB_HANDSHAKE_START
165 Callback has been called because a new handshake is started.
166 .It Dv SSL_CB_HANDSHAKE_DONE
167 Callback has been called because a handshake is finished.
168 .El
169 .Pp
170 The current state information can be obtained using the
171 .Xr SSL_state_string 3
172 family of functions.
173 .Pp
174 The
175 .Fa ret
176 information can be evaluated using the
177 .Xr SSL_alert_type_string 3
178 family of functions.
179 .Sh RETURN VALUES
180 .Fn SSL_CTX_get_info_callback
181 and
182 .Fn SSL_get_info_callback
183 return a pointer to the current callback or
184 .Dv NULL
185 if none is set.
186 .Sh EXAMPLES
187 The following example callback function prints state strings,
188 information about alerts being handled and error messages to the
189 .Va bio_err
190 .Vt BIO .
191 .Bd -literal
192 void
193 apps_ssl_info_callback(SSL *s, int where, int ret)
194 {
195 const char *str;
196 int w;
198 w = where & ~SSL_ST_MASK;
200 if (w & SSL_ST_CONNECT)
201 str = "SSL_connect";
202 else if (w & SSL_ST_ACCEPT)
203 str = "SSL_accept";
204 else
205 str = "undefined";
207 if (where & SSL_CB_LOOP) {
208 BIO_printf(bio_err, "%s:%s\en", str,
209 SSL_state_string_long(s));
210 } else if (where & SSL_CB_ALERT) {
211 str = (where & SSL_CB_READ) ? "read" : "write";
212 BIO_printf(bio_err, "SSL3 alert %s:%s:%s\en", str,
213 SSL_alert_type_string_long(ret),
214 SSL_alert_desc_string_long(ret));
215 } else if (where & SSL_CB_EXIT) {
216 if (ret == 0)
217 BIO_printf(bio_err, "%s:failed in %s\en",
218 str, SSL_state_string_long(s));
219 else if (ret < 0) {
220 BIO_printf(bio_err, "%s:error in %s\en",
221 str, SSL_state_string_long(s));
222 }
223 }
224 }
225 .Ed
226 .Sh SEE ALSO
227 .Xr ssl 3 ,
228 .Xr SSL_alert_type_string 3 ,
229 .Xr SSL_state_string 3
230 .Sh HISTORY
231 These functions appeared before SSLeay 0.8 and have been available since
232 .Ox 2.4 .