From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001
From: Wojtek Kosior <wk@koszkonutek-tmp.pl.eu.org>
Date: Fri, 30 Apr 2021 00:33:56 +0200
Subject: initial/final commit

---
 .../doc/ssl/SSL_CTX_set_info_callback.pod          | 162 +++++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod

(limited to 'openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod')

diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod
new file mode 100644
index 0000000..f36f217
--- /dev/null
+++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod
@@ -0,0 +1,162 @@
+=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)());
+ void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))();
+
+ void SSL_set_info_callback(SSL *ssl, void (*callback)());
+ void (*SSL_get_info_callback(const SSL *ssl))();
+
+=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.
+When B<callback> is NULL, no callback function is used.
+
+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)
+the callback function was called. If B<ret> is 0, an error condition occurred.
+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
+L<SSL_state_string(3)> family of functions.
+
+The B<ret> information can be evaluated using the
+L<SSL_alert_type_string(3)> family of functions.
+
+=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
+
+L<ssl(3)>, L<SSL_state_string(3)>,
+L<SSL_alert_type_string(3)>
+
+=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
-- 
cgit v1.2.3