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