.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SSL_GET_CONN_CLOSE_INFO 3ossl"
.TH SSL_GET_CONN_CLOSE_INFO 3ossl "2024-06-04" "3.3.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 \fISSL_get_conn_close_info()\fR function provides information about why and how a
\&\s-1QUIC\s0 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(CW\*(C`sizeof(*info)\*(C'\fR.
.PP
The following fields are set:
.IP "\fIerror_code\fR" 4
.IX Item "error_code"
This is a 62\-bit \s-1QUIC\s0 error code. It is either a 62\-bit application error code
(if \fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\fR not set in \fIflags\fR) or a  62\-bit standard
\&\s-1QUIC\s0 transport error code (if \fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\fR is set in
\&\fIflags\fR).
.IP "\fIframe_type\fR" 4
.IX Item "frame_type"
If \fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\fR is set, this may be set to a \s-1QUIC\s0 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
\&\fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\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 \s-1UTF\-8\s0 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 \s-1QUIC\s0 protocol that this be a \s-1UTF\-8\s0 string, there
is no guarantee that this is the case for strings received from the peer.
.IP "\fB\s-1SSL_CONN_CLOSE_FLAG_LOCAL\s0\fR" 4
.IX Item "SSL_CONN_CLOSE_FLAG_LOCAL"
If \fIflags\fR has \fB\s-1SSL_CONN_CLOSE_FLAG_LOCAL\s0\fR set, connection closure was locally
triggered. This could be due to an application request (e.g. if
\&\fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\fR is unset), or (if
\&\fI\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\fR is set) due to logic internal to the \s-1QUIC\s0
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 "\fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\fR" 4
.IX Item "SSL_CONN_CLOSE_FLAG_TRANSPORT"
If \fIflags\fR has \fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\fR set, connection closure was
triggered for \s-1QUIC\s0 protocol reasons. Otherwise, connection closure was triggered
by the local or remote application.
.PP
The \fB\s-1OSSL_QUIC_ERR\s0\fR macro definitions provide the \s-1QUIC\s0 transport error codes as
defined by \s-1RFC 9000.\s0 The \s-1\fIOSSL_QUIC_ERR_CRYPTO_ERR\s0()\fR macro can be used to convert
a \s-1TLS\s0 alert code into a \s-1QUIC\s0 transport error code by mapping it into the range
reserved for such codes by \s-1RFC 9000.\s0 This range begins at
\&\fB\s-1OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN\s0\fR and ends at \fB\s-1OSSL_QUIC_ERR_CRYPTO_ERR_END\s0\fR
inclusive.
.SH "NON-STANDARD TRANSPORT ERROR CODES"
.IX Header "NON-STANDARD TRANSPORT ERROR CODES"
Some conditions which can cause \s-1QUIC\s0 connection termination are not signalled on
the wire and therefore do not have standard error codes. OpenSSL indicates these
errors via \fISSL_get_conn_close_info()\fR by setting \fB\s-1SSL_CONN_CLOSE_FLAG_TRANSPORT\s0\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 "\fB\s-1OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT\s0\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"
\&\fISSL_get_conn_close_info()\fR returns 1 on success and 0 on failure. This function
fails if called on a \s-1QUIC\s0 connection \s-1SSL\s0 object which has not yet been
terminated. It also fails if called on a \s-1QUIC\s0 stream \s-1SSL\s0 object or a non-QUIC
\&\s-1SSL\s0 object.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISSL_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 \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.