diff options
Diffstat (limited to 'doc/man3/SSL_get_conn_close_info.pod')
| -rw-r--r-- | doc/man3/SSL_get_conn_close_info.pod | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/doc/man3/SSL_get_conn_close_info.pod b/doc/man3/SSL_get_conn_close_info.pod new file mode 100644 index 0000000000..5f9a2c3e38 --- /dev/null +++ b/doc/man3/SSL_get_conn_close_info.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_get_conn_close_info - get information about why a QUIC connection was closed + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + typedef struct ssl_conn_close_info_st { + uint64_t error_code; + char *reason; + size_t reason_len; + char is_local; + char is_transport; + } SSL_CONN_CLOSE_INFO; + + int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info, + size_t info_len); + +=head1 DESCRIPTION + +The SSL_get_conn_close_info() function provides information about why and how a +QUIC connection was closed. + +Connection closure information is written to B<*info>, which must be non-NULL. +B<info_len> must be set to B<sizeof(*info)>. + +The following fields are set: + +=over 4 + +=item B<error_code> + +This is a 62-bit QUIC error code. It is either a 62-bit application error code +(if B<is_transport> is 0) or a 62-bit standard QUIC transport error code (if +B<is_transport> is 1). + +=item B<reason> + +If non-NULL, this is intended to be a UTF-8 textual string briefly describing +the reason for connection closure. The length of the reason string in bytes is +given in B<reason_len>. While, if non-NULL, OpenSSL guarantees that this string +will be zero terminated, consider that this buffer may originate from the +(untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use +of B<reason_len> is recommended. + +While it is intended as per the QUIC protocol that this be a UTF-8 string, there +is no guarantee that this is the case for strings received from the peer. + +=item B<is_local> + +If 1, connection closure was locally triggered. This could be due to an +application request (e.g. if B<is_transport> is 0), or (if B<is_transport> is 1) +due to logic internal to the QUIC implementation (for example, if the peer +engages in a protocol violation, or an idle timeout occurs). + +If 0, connection closure was remotely triggered. + +=item B<is_transport> + +If 1, connection closure was triggered for QUIC protocol reasons. + +If 0, connection closure was triggered by the local or remote application. + +=back + +=head1 RETURN VALUES + +SSL_get_conn_close_info() returns 1 on success and 0 on failure. This function +fails if called on a QUIC connection SSL object which has not yet been +terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC +SSL object. + +=head1 SEE ALSO + +L<SSL_shutdown_ex(3)> + +=head1 HISTORY + +This function was added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (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 |