SSL_CTX_set_info_callback.pod 4.5 KB
Newer Older
L
Lutz Jänicke 已提交
1 2 3 4 5 6 7 8 9 10 11
=pod

=head1 NAME

SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)());
12
 void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
L
Lutz Jänicke 已提交
13 14

 void SSL_set_info_callback(SSL *ssl, void (*callback)());
15
 void (*SSL_get_info_callback(const SSL *ssl))();
L
Lutz Jänicke 已提交
16 17 18 19 20 21 22

=head1 DESCRIPTION

SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to
obtain state information for SSL objects created from B<ctx> during connection
setup and use. The setting for B<ctx> is overridden from the setting for
a specific SSL object, if specified.
R
Rich Salz 已提交
23
When B<callback> is NULL, no callback function is used.
L
Lutz Jänicke 已提交
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

SSL_set_info_callback() sets the B<callback> function, that can be used to
obtain state information for B<ssl> during connection setup and use.
When B<callback> is NULL, the callback setting currently valid for
B<ctx> is used.

SSL_CTX_get_info_callback() returns a pointer to the currently set information
callback function for B<ctx>.

SSL_get_info_callback() returns a pointer to the currently set information
callback function for B<ssl>.

=head1 NOTES

When setting up a connection and during use, it is possible to obtain state
information from the SSL/TLS engine. When set, an information callback function
is called whenever the state changes, an alert appears, or an error occurs.

The callback function is called as B<callback(SSL *ssl, int where, int ret)>.
The B<where> argument specifies information about where (in which context)
U
ispell  
Ulf Möller 已提交
44
the callback function was called. If B<ret> is 0, an error condition occurred.
L
Lutz Jänicke 已提交
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert
information.

B<where> is a bitmask made up of the following bits:

=over 4

=item SSL_CB_LOOP

Callback has been called to indicate state change inside a loop.

=item SSL_CB_EXIT

Callback has been called to indicate error exit of a handshake function.
(May be soft error with retry option for non-blocking setups.)

=item SSL_CB_READ

Callback has been called during read operation.

=item SSL_CB_WRITE

Callback has been called during write operation.

=item SSL_CB_ALERT

Callback has been called due to an alert being sent or received.

=item SSL_CB_READ_ALERT               (SSL_CB_ALERT|SSL_CB_READ)

=item SSL_CB_WRITE_ALERT              (SSL_CB_ALERT|SSL_CB_WRITE)

=item SSL_CB_ACCEPT_LOOP              (SSL_ST_ACCEPT|SSL_CB_LOOP)

=item SSL_CB_ACCEPT_EXIT              (SSL_ST_ACCEPT|SSL_CB_EXIT)

=item SSL_CB_CONNECT_LOOP             (SSL_ST_CONNECT|SSL_CB_LOOP)

=item SSL_CB_CONNECT_EXIT             (SSL_ST_CONNECT|SSL_CB_EXIT)

=item SSL_CB_HANDSHAKE_START

Callback has been called because a new handshake is started.

=item SSL_CB_HANDSHAKE_DONE           0x20

Callback has been called because a handshake is finished.

=back

The current state information can be obtained using the
R
Rich Salz 已提交
96
L<SSL_state_string(3)> family of functions.
L
Lutz Jänicke 已提交
97 98

The B<ret> information can be evaluated using the
R
Rich Salz 已提交
99
L<SSL_alert_type_string(3)> family of functions.
L
Lutz Jänicke 已提交
100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149

=head1 RETURN VALUES

SSL_set_info_callback() does not provide diagnostic information.

SSL_get_info_callback() returns the current setting.

=head1 EXAMPLES

The following example callback function prints state strings, information
about alerts being handled and error messages to the B<bio_err> BIO.

 void apps_ssl_info_callback(SSL *s, int where, int ret)
	{
	const char *str;
	int w;

	w=where& ~SSL_ST_MASK;

	if (w & SSL_ST_CONNECT) str="SSL_connect";
	else if (w & SSL_ST_ACCEPT) str="SSL_accept";
	else str="undefined";

	if (where & SSL_CB_LOOP)
		{
		BIO_printf(bio_err,"%s:%s\n",str,SSL_state_string_long(s));
		}
	else if (where & SSL_CB_ALERT)
		{
		str=(where & SSL_CB_READ)?"read":"write";
		BIO_printf(bio_err,"SSL3 alert %s:%s:%s\n",
			str,
			SSL_alert_type_string_long(ret),
			SSL_alert_desc_string_long(ret));
		}
	else if (where & SSL_CB_EXIT)
		{
		if (ret == 0)
			BIO_printf(bio_err,"%s:failed in %s\n",
				str,SSL_state_string_long(s));
		else if (ret < 0)
			{
			BIO_printf(bio_err,"%s:error in %s\n",
				str,SSL_state_string_long(s));
			}
		}
	}

=head1 SEE ALSO

R
Rich Salz 已提交
150 151
L<ssl(3)>, L<SSL_state_string(3)>,
L<SSL_alert_type_string(3)>
L
Lutz Jänicke 已提交
152 153

=cut
R
Rich Salz 已提交
154 155 156 157 158 159 160 161 162 163 164

=head1 COPYRIGHT

Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut