diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/SSL_get_conn_close_info.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/SSL_get_conn_close_info.3 | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/SSL_get_conn_close_info.3 b/secure/lib/libcrypto/man/man3/SSL_get_conn_close_info.3 new file mode 100644 index 000000000000..9321bb6fc7a6 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/SSL_get_conn_close_info.3 @@ -0,0 +1,215 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "SSL_GET_CONN_CLOSE_INFO 3ossl" +.TH SSL_GET_CONN_CLOSE_INFO 3ossl 2025-07-01 3.5.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL, +SSL_CONN_CLOSE_FLAG_TRANSPORT, +OSSL_QUIC_ERR_NO_ERROR, +OSSL_QUIC_ERR_INTERNAL_ERROR, +OSSL_QUIC_ERR_CONNECTION_REFUSED, +OSSL_QUIC_ERR_FLOW_CONTROL_ERROR, +OSSL_QUIC_ERR_STREAM_LIMIT_ERROR, +OSSL_QUIC_ERR_STREAM_STATE_ERROR, +OSSL_QUIC_ERR_FINAL_SIZE_ERROR, +OSSL_QUIC_ERR_FRAME_ENCODING_ERROR, +OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR, +OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR, +OSSL_QUIC_ERR_PROTOCOL_VIOLATION, +OSSL_QUIC_ERR_INVALID_TOKEN, +OSSL_QUIC_ERR_APPLICATION_ERROR, +OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED, +OSSL_QUIC_ERR_KEY_UPDATE_ERROR, +OSSL_QUIC_ERR_AEAD_LIMIT_REACHED, +OSSL_QUIC_ERR_NO_VIABLE_PATH, +OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN, +OSSL_QUIC_ERR_CRYPTO_ERR_END, +OSSL_QUIC_ERR_CRYPTO_ERR, +OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT +\&\- get information about why a QUIC connection was closed +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/ssl.h> +\& +\& #define SSL_CONN_CLOSE_FLAG_LOCAL +\& #define SSL_CONN_CLOSE_FLAG_TRANSPORT +\& +\& typedef struct ssl_conn_close_info_st { +\& uint64_t error_code, frame_type; +\& char *reason; +\& size_t reason_len; +\& uint32_t flags; +\& } SSL_CONN_CLOSE_INFO; +\& +\& int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info, +\& size_t info_len); +\& +\& #define OSSL_QUIC_ERR_NO_ERROR 0x00 +\& #define OSSL_QUIC_ERR_INTERNAL_ERROR 0x01 +\& #define OSSL_QUIC_ERR_CONNECTION_REFUSED 0x02 +\& #define OSSL_QUIC_ERR_FLOW_CONTROL_ERROR 0x03 +\& #define OSSL_QUIC_ERR_STREAM_LIMIT_ERROR 0x04 +\& #define OSSL_QUIC_ERR_STREAM_STATE_ERROR 0x05 +\& #define OSSL_QUIC_ERR_FINAL_SIZE_ERROR 0x06 +\& #define OSSL_QUIC_ERR_FRAME_ENCODING_ERROR 0x07 +\& #define OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR 0x08 +\& #define OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR 0x09 +\& #define OSSL_QUIC_ERR_PROTOCOL_VIOLATION 0x0A +\& #define OSSL_QUIC_ERR_INVALID_TOKEN 0x0B +\& #define OSSL_QUIC_ERR_APPLICATION_ERROR 0x0C +\& #define OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED 0x0D +\& #define OSSL_QUIC_ERR_KEY_UPDATE_ERROR 0x0E +\& #define OSSL_QUIC_ERR_AEAD_LIMIT_REACHED 0x0F +\& #define OSSL_QUIC_ERR_NO_VIABLE_PATH 0x10 +\& +\& /* Inclusive range for handshake\-specific errors. */ +\& #define OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN 0x0100 +\& #define OSSL_QUIC_ERR_CRYPTO_ERR_END 0x01FF +\& +\& #define OSSL_QUIC_ERR_CRYPTO_ERR(X) +\& +\& #define OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBSSL_get_conn_close_info()\fR function provides information about why and how a +QUIC connection was closed. +.PP +Connection closure information is written to \fI*info\fR, which must be non-NULL. +\&\fIinfo_len\fR must be set to \f(CWsizeof(*info)\fR. +.PP +The following fields are set: +.IP \fIerror_code\fR 4 +.IX Item "error_code" +This is a 62\-bit QUIC error code. It is either a 62\-bit application error code +(if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR not set in \fIflags\fR) or a 62\-bit standard +QUIC transport error code (if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set in +\&\fIflags\fR). +.IP \fIframe_type\fR 4 +.IX Item "frame_type" +If \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set, this may be set to a QUIC frame type +number which caused the connection to be closed. It may also be set to 0 if no +frame type was specified as causing the connection to be closed. If +\&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is not set, this is set to 0. +.IP \fIreason\fR 4 +.IX Item "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 \fIreason_len\fR. 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 \fIreason_len\fR is recommended. +.Sp +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. +.IP \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR 4 +.IX Item "SSL_CONN_CLOSE_FLAG_LOCAL" +If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR set, connection closure was locally +triggered. This could be due to an application request (e.g. if +\&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is unset), or (if +\&\fISSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set) due to logic internal to the QUIC +implementation (for example, if the peer engages in a protocol violation, or an +idle timeout occurs). +.Sp +If unset, connection closure was remotely triggered. +.IP \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR 4 +.IX Item "SSL_CONN_CLOSE_FLAG_TRANSPORT" +If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR set, connection closure was +triggered for QUIC protocol reasons. Otherwise, connection closure was triggered +by the local or remote application. +.PP +The \fBOSSL_QUIC_ERR\fR macro definitions provide the QUIC transport error codes as +defined by RFC 9000. The \fBOSSL_QUIC_ERR_CRYPTO_ERR()\fR macro can be used to convert +a TLS alert code into a QUIC transport error code by mapping it into the range +reserved for such codes by RFC 9000. This range begins at +\&\fBOSSL_QUIC_ERR_CRYPTO_ERR_BEGIN\fR and ends at \fBOSSL_QUIC_ERR_CRYPTO_ERR_END\fR +inclusive. +.SH "NON-STANDARD TRANSPORT ERROR CODES" +.IX Header "NON-STANDARD TRANSPORT ERROR CODES" +Some conditions which can cause QUIC connection termination are not signalled on +the wire and therefore do not have standard error codes. OpenSSL indicates these +errors via \fBSSL_get_conn_close_info()\fR by setting \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR +and using one of the following error values. These codes are specific to +OpenSSL, and cannot be sent over the wire, as they are above 2**62. +.IP \fBOSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT\fR 4 +.IX Item "OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT" +The connection was terminated immediately due to the idle timeout expiring. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_get_conn_close_info()\fR 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. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_shutdown_ex\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This function was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 +<https://www.openssl.org/source/license.html>. |