1.\" $OpenBSD: SSL_CTX_set_info_callback.3,v 1.4 2018/03/27 17:35:50 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 27 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 86sets the 87.Fa callback 88function that can be used to obtain state information for SSL objects created 89from 90.Fa ctx 91during connection setup and use. 92The setting for 93.Fa ctx 94is overridden from the setting for a specific SSL object, if specified. 95When 96.Fa callback 97is 98.Dv NULL , 99no callback function is used. 100.Pp 101.Fn SSL_set_info_callback 102sets the 103.Fa callback 104function that can be used to 105obtain state information for 106.Fa ssl 107during connection setup and use. 108When 109.Fa callback 110is 111.Dv NULL , 112the callback setting currently valid for 113.Fa ctx 114is used. 115.Pp 116.Fn SSL_CTX_get_info_callback 117returns a pointer to the currently set information callback function for 118.Fa ctx . 119.Pp 120.Fn SSL_get_info_callback 121returns a pointer to the currently set information callback function for 122.Fa ssl . 123.Pp 124When setting up a connection and during use, 125it is possible to obtain state information from the SSL/TLS engine. 126When set, an information callback function is called whenever the state changes, 127an alert appears, or an error occurs. 128.Pp 129The callback function is called as 130.Fn callback "SSL *ssl" "int where" "int ret" . 131The 132.Fa where 133argument specifies information about where (in which context) 134the callback function was called. 135If 136.Fa ret 137is 0, an error condition occurred. 138If an alert is handled, 139.Dv SSL_CB_ALERT 140is set and 141.Fa ret 142specifies the alert information. 143.Pp 144.Fa where 145is a bitmask made up of the following bits: 146.Bl -tag -width Ds 147.It Dv SSL_CB_LOOP 148Callback has been called to indicate state change inside a loop. 149.It Dv SSL_CB_EXIT 150Callback 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 153Callback has been called during read operation. 154.It Dv SSL_CB_WRITE 155Callback has been called during write operation. 156.It Dv SSL_CB_ALERT 157Callback 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 165Callback has been called because a new handshake is started. 166.It Dv SSL_CB_HANDSHAKE_DONE 167Callback has been called because a handshake is finished. 168.El 169.Pp 170The current state information can be obtained using the 171.Xr SSL_state_string 3 172family of functions. 173.Pp 174The 175.Fa ret 176information can be evaluated using the 177.Xr SSL_alert_type_string 3 178family of functions. 179.Sh RETURN VALUES 180.Fn SSL_CTX_get_info_callback 181and 182.Fn SSL_get_info_callback 183return a pointer to the current callback or 184.Dv NULL 185if none is set. 186.Sh EXAMPLES 187The following example callback function prints state strings, 188information about alerts being handled and error messages to the 189.Va bio_err 190.Vt BIO . 191.Bd -literal 192void 193apps_ssl_info_callback(SSL *s, int where, int ret) 194{ 195 const char *str; 196 int w; 197 198 w = where & ~SSL_ST_MASK; 199 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"; 206 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 231These functions first appeared in SSLeay 0.6.0 232and have been available since 233.Ox 2.4 . 234