1=pod
2
3=head1 NAME
4
5SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL,
6SSL_CONN_CLOSE_FLAG_TRANSPORT,
7OSSL_QUIC_ERR_NO_ERROR,
8OSSL_QUIC_ERR_INTERNAL_ERROR,
9OSSL_QUIC_ERR_CONNECTION_REFUSED,
10OSSL_QUIC_ERR_FLOW_CONTROL_ERROR,
11OSSL_QUIC_ERR_STREAM_LIMIT_ERROR,
12OSSL_QUIC_ERR_STREAM_STATE_ERROR,
13OSSL_QUIC_ERR_FINAL_SIZE_ERROR,
14OSSL_QUIC_ERR_FRAME_ENCODING_ERROR,
15OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR,
16OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR,
17OSSL_QUIC_ERR_PROTOCOL_VIOLATION,
18OSSL_QUIC_ERR_INVALID_TOKEN,
19OSSL_QUIC_ERR_APPLICATION_ERROR,
20OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED,
21OSSL_QUIC_ERR_KEY_UPDATE_ERROR,
22OSSL_QUIC_ERR_AEAD_LIMIT_REACHED,
23OSSL_QUIC_ERR_NO_VIABLE_PATH,
24OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN,
25OSSL_QUIC_ERR_CRYPTO_ERR_END,
26OSSL_QUIC_ERR_CRYPTO_ERR,
27OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT
28- get information about why a QUIC connection was closed
29
30=head1 SYNOPSIS
31
32 #include <openssl/ssl.h>
33
34 #define SSL_CONN_CLOSE_FLAG_LOCAL
35 #define SSL_CONN_CLOSE_FLAG_TRANSPORT
36
37 typedef struct ssl_conn_close_info_st {
38     uint64_t error_code, frame_type;
39     char     *reason;
40     size_t   reason_len;
41     uint32_t flags;
42 } SSL_CONN_CLOSE_INFO;
43
44 int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info,
45                             size_t info_len);
46
47 #define OSSL_QUIC_ERR_NO_ERROR                  0x00
48 #define OSSL_QUIC_ERR_INTERNAL_ERROR            0x01
49 #define OSSL_QUIC_ERR_CONNECTION_REFUSED        0x02
50 #define OSSL_QUIC_ERR_FLOW_CONTROL_ERROR        0x03
51 #define OSSL_QUIC_ERR_STREAM_LIMIT_ERROR        0x04
52 #define OSSL_QUIC_ERR_STREAM_STATE_ERROR        0x05
53 #define OSSL_QUIC_ERR_FINAL_SIZE_ERROR          0x06
54 #define OSSL_QUIC_ERR_FRAME_ENCODING_ERROR      0x07
55 #define OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR 0x08
56 #define OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR 0x09
57 #define OSSL_QUIC_ERR_PROTOCOL_VIOLATION        0x0A
58 #define OSSL_QUIC_ERR_INVALID_TOKEN             0x0B
59 #define OSSL_QUIC_ERR_APPLICATION_ERROR         0x0C
60 #define OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED    0x0D
61 #define OSSL_QUIC_ERR_KEY_UPDATE_ERROR          0x0E
62 #define OSSL_QUIC_ERR_AEAD_LIMIT_REACHED        0x0F
63 #define OSSL_QUIC_ERR_NO_VIABLE_PATH            0x10
64
65 /* Inclusive range for handshake-specific errors. */
66 #define OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN          0x0100
67 #define OSSL_QUIC_ERR_CRYPTO_ERR_END            0x01FF
68
69 #define OSSL_QUIC_ERR_CRYPTO_ERR(X)
70
71 #define OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT
72
73=head1 DESCRIPTION
74
75The SSL_get_conn_close_info() function provides information about why and how a
76QUIC connection was closed.
77
78Connection closure information is written to I<*info>, which must be non-NULL.
79I<info_len> must be set to C<sizeof(*info)>.
80
81The following fields are set:
82
83=over 4
84
85=item I<error_code>
86
87This is a 62-bit QUIC error code. It is either a 62-bit application error code
88(if B<SSL_CONN_CLOSE_FLAG_TRANSPORT> not set in I<flags>) or a  62-bit standard
89QUIC transport error code (if B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is set in
90I<flags>).
91
92=item I<frame_type>
93
94If B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is set, this may be set to a QUIC frame type
95number which caused the connection to be closed. It may also be set to 0 if no
96frame type was specified as causing the connection to be closed. If
97B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is not set, this is set to 0.
98
99=item I<reason>
100
101If non-NULL, this is intended to be a UTF-8 textual string briefly describing
102the reason for connection closure. The length of the reason string in bytes is
103given in I<reason_len>. While, if non-NULL, OpenSSL guarantees that this string
104will be zero terminated, consider that this buffer may originate from the
105(untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use
106of I<reason_len> is recommended.
107
108While it is intended as per the QUIC protocol that this be a UTF-8 string, there
109is no guarantee that this is the case for strings received from the peer.
110
111=item B<SSL_CONN_CLOSE_FLAG_LOCAL>
112
113If I<flags> has B<SSL_CONN_CLOSE_FLAG_LOCAL> set, connection closure was locally
114triggered. This could be due to an application request (e.g. if
115B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is unset), or (if
116I<SSL_CONN_CLOSE_FLAG_TRANSPORT> is set) due to logic internal to the QUIC
117implementation (for example, if the peer engages in a protocol violation, or an
118idle timeout occurs).
119
120If unset, connection closure was remotely triggered.
121
122=item B<SSL_CONN_CLOSE_FLAG_TRANSPORT>
123
124If I<flags> has B<SSL_CONN_CLOSE_FLAG_TRANSPORT> set, connection closure was
125triggered for QUIC protocol reasons. Otherwise, connection closure was triggered
126by the local or remote application.
127
128=back
129
130The B<OSSL_QUIC_ERR> macro definitions provide the QUIC transport error codes as
131defined by RFC 9000. The OSSL_QUIC_ERR_CRYPTO_ERR() macro can be used to convert
132a TLS alert code into a QUIC transport error code by mapping it into the range
133reserved for such codes by RFC 9000. This range begins at
134B<OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN> and ends at B<OSSL_QUIC_ERR_CRYPTO_ERR_END>
135inclusive.
136
137=head1 NON-STANDARD TRANSPORT ERROR CODES
138
139Some conditions which can cause QUIC connection termination are not signalled on
140the wire and therefore do not have standard error codes. OpenSSL indicates these
141errors via SSL_get_conn_close_info() by setting B<SSL_CONN_CLOSE_FLAG_TRANSPORT>
142and using one of the following error values. These codes are specific to
143OpenSSL, and cannot be sent over the wire, as they are above 2**62.
144
145=over 4
146
147=item B<OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT>
148
149The connection was terminated immediately due to the idle timeout expiring.
150
151=back
152
153=head1 RETURN VALUES
154
155SSL_get_conn_close_info() returns 1 on success and 0 on failure. This function
156fails if called on a QUIC connection SSL object which has not yet been
157terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC
158SSL object.
159
160=head1 SEE ALSO
161
162L<SSL_shutdown_ex(3)>
163
164=head1 HISTORY
165
166This function was added in OpenSSL 3.2.
167
168=head1 COPYRIGHT
169
170Copyright 2002-2024 The OpenSSL Project Authors. All Rights Reserved.
171
172Licensed under the Apache License 2.0 (the "License").  You may not use
173this file except in compliance with the License.  You can obtain a copy
174in the file LICENSE in the source distribution or at
175L<https://www.openssl.org/source/license.html>.
176
177=cut
178