Debian Codegraph @

upstream/debian-unstable/man3/SSL_get_conn_close_info.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_GET_CONN_CLOSE_INFO 3SSL"
58 .TH SSL_GET_CONN_CLOSE_INFO 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL,
65 SSL_CONN_CLOSE_FLAG_TRANSPORT,
66 OSSL_QUIC_ERR_NO_ERROR,
67 OSSL_QUIC_ERR_INTERNAL_ERROR,
68 OSSL_QUIC_ERR_CONNECTION_REFUSED,
69 OSSL_QUIC_ERR_FLOW_CONTROL_ERROR,
70 OSSL_QUIC_ERR_STREAM_LIMIT_ERROR,
71 OSSL_QUIC_ERR_STREAM_STATE_ERROR,
72 OSSL_QUIC_ERR_FINAL_SIZE_ERROR,
73 OSSL_QUIC_ERR_FRAME_ENCODING_ERROR,
74 OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR,
75 OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR,
76 OSSL_QUIC_ERR_PROTOCOL_VIOLATION,
77 OSSL_QUIC_ERR_INVALID_TOKEN,
78 OSSL_QUIC_ERR_APPLICATION_ERROR,
79 OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED,
80 OSSL_QUIC_ERR_KEY_UPDATE_ERROR,
81 OSSL_QUIC_ERR_AEAD_LIMIT_REACHED,
82 OSSL_QUIC_ERR_NO_VIABLE_PATH,
83 OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN,
84 OSSL_QUIC_ERR_CRYPTO_ERR_END,
85 OSSL_QUIC_ERR_CRYPTO_ERR,
86 OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT
87 \&\- get information about why a QUIC connection was closed
88 .SH SYNOPSIS
89 .IX Header "SYNOPSIS"
90 .Vb 1
91 \& #include <openssl/ssl.h>
92 \&
93 \& #define SSL_CONN_CLOSE_FLAG_LOCAL
94 \& #define SSL_CONN_CLOSE_FLAG_TRANSPORT
95 \&
96 \& typedef struct ssl_conn_close_info_st {
97 \& uint64_t error_code, frame_type;
98 \& char *reason;
99 \& size_t reason_len;
100 \& uint32_t flags;
101 \& } SSL_CONN_CLOSE_INFO;
102 \&
103 \& int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info,
104 \& size_t info_len);
105 \&
106 \& #define OSSL_QUIC_ERR_NO_ERROR 0x00
107 \& #define OSSL_QUIC_ERR_INTERNAL_ERROR 0x01
108 \& #define OSSL_QUIC_ERR_CONNECTION_REFUSED 0x02
109 \& #define OSSL_QUIC_ERR_FLOW_CONTROL_ERROR 0x03
110 \& #define OSSL_QUIC_ERR_STREAM_LIMIT_ERROR 0x04
111 \& #define OSSL_QUIC_ERR_STREAM_STATE_ERROR 0x05
112 \& #define OSSL_QUIC_ERR_FINAL_SIZE_ERROR 0x06
113 \& #define OSSL_QUIC_ERR_FRAME_ENCODING_ERROR 0x07
114 \& #define OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR 0x08
115 \& #define OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR 0x09
116 \& #define OSSL_QUIC_ERR_PROTOCOL_VIOLATION 0x0A
117 \& #define OSSL_QUIC_ERR_INVALID_TOKEN 0x0B
118 \& #define OSSL_QUIC_ERR_APPLICATION_ERROR 0x0C
119 \& #define OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED 0x0D
120 \& #define OSSL_QUIC_ERR_KEY_UPDATE_ERROR 0x0E
121 \& #define OSSL_QUIC_ERR_AEAD_LIMIT_REACHED 0x0F
122 \& #define OSSL_QUIC_ERR_NO_VIABLE_PATH 0x10
123 \&
124 \& /* Inclusive range for handshake\-specific errors. */
125 \& #define OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN 0x0100
126 \& #define OSSL_QUIC_ERR_CRYPTO_ERR_END 0x01FF
127 \&
128 \& #define OSSL_QUIC_ERR_CRYPTO_ERR(X)
129 \&
130 \& #define OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT
131 .Ve
132 .SH DESCRIPTION
133 .IX Header "DESCRIPTION"
134 The \fBSSL_get_conn_close_info()\fR function provides information about why and how a
135 QUIC connection was closed.
136 .PP
137 Connection closure information is written to \fI*info\fR, which must be non-NULL.
138 \&\fIinfo_len\fR must be set to \f(CWsizeof(*info)\fR.
139 .PP
140 The following fields are set:
141 .IP \fIerror_code\fR 4
142 .IX Item "error_code"
143 This is a 62\-bit QUIC error code. It is either a 62\-bit application error code
144 (if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR not set in \fIflags\fR) or a 62\-bit standard
145 QUIC transport error code (if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set in
146 \&\fIflags\fR).
147 .IP \fIframe_type\fR 4
148 .IX Item "frame_type"
149 If \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set, this may be set to a QUIC frame type
150 number which caused the connection to be closed. It may also be set to 0 if no
151 frame type was specified as causing the connection to be closed. If
152 \&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is not set, this is set to 0.
153 .IP \fIreason\fR 4
154 .IX Item "reason"
155 If non-NULL, this is intended to be a UTF\-8 textual string briefly describing
156 the reason for connection closure. The length of the reason string in bytes is
157 given in \fIreason_len\fR. While, if non-NULL, OpenSSL guarantees that this string
158 will be zero terminated, consider that this buffer may originate from the
159 (untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use
160 of \fIreason_len\fR is recommended.
161 .Sp
162 While it is intended as per the QUIC protocol that this be a UTF\-8 string, there
163 is no guarantee that this is the case for strings received from the peer.
164 .IP \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR 4
165 .IX Item "SSL_CONN_CLOSE_FLAG_LOCAL"
166 If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR set, connection closure was locally
167 triggered. This could be due to an application request (e.g. if
168 \&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is unset), or (if
169 \&\fISSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set) due to logic internal to the QUIC
170 implementation (for example, if the peer engages in a protocol violation, or an
171 idle timeout occurs).
172 .Sp
173 If unset, connection closure was remotely triggered.
174 .IP \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR 4
175 .IX Item "SSL_CONN_CLOSE_FLAG_TRANSPORT"
176 If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR set, connection closure was
177 triggered for QUIC protocol reasons. Otherwise, connection closure was triggered
178 by the local or remote application.
179 .PP
180 The \fBOSSL_QUIC_ERR\fR macro definitions provide the QUIC transport error codes as
181 defined by RFC 9000. The \fBOSSL_QUIC_ERR_CRYPTO_ERR()\fR macro can be used to convert
182 a TLS alert code into a QUIC transport error code by mapping it into the range
183 reserved for such codes by RFC 9000. This range begins at
184 \&\fBOSSL_QUIC_ERR_CRYPTO_ERR_BEGIN\fR and ends at \fBOSSL_QUIC_ERR_CRYPTO_ERR_END\fR
185 inclusive.
186 .SH "NON-STANDARD TRANSPORT ERROR CODES"
187 .IX Header "NON-STANDARD TRANSPORT ERROR CODES"
188 Some conditions which can cause QUIC connection termination are not signalled on
189 the wire and therefore do not have standard error codes. OpenSSL indicates these
190 errors via \fBSSL_get_conn_close_info()\fR by setting \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR
191 and using one of the following error values. These codes are specific to
192 OpenSSL, and cannot be sent over the wire, as they are above 2**62.
193 .IP \fBOSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT\fR 4
194 .IX Item "OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT"
195 The connection was terminated immediately due to the idle timeout expiring.
196 .SH "RETURN VALUES"
197 .IX Header "RETURN VALUES"
198 \&\fBSSL_get_conn_close_info()\fR returns 1 on success and 0 on failure. This function
199 fails if called on a QUIC connection SSL object which has not yet been
200 terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC
201 SSL object.
202 .SH "SEE ALSO"
203 .IX Header "SEE ALSO"
204 \&\fBSSL_shutdown_ex\fR\|(3)
205 .SH HISTORY
206 .IX Header "HISTORY"
207 This function was added in OpenSSL 3.2.
208 .SH COPYRIGHT
209 .IX Header "COPYRIGHT"
210 Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved.
211 .PP
212 Licensed under the Apache License 2.0 (the "License"). You may not use
213 this file except in compliance with the License. You can obtain a copy
214 in the file LICENSE in the source distribution or at
215 <https://www.openssl.org/source/license.html>.