]>
Commit | Line | Data |
---|---|---|
1e4a9d88 HL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
7d9e447a HL |
5 | SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL, |
6 | SSL_CONN_CLOSE_FLAG_TRANSPORT - get information about why a QUIC connection was | |
7 | closed | |
1e4a9d88 HL |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/ssl.h> | |
12 | ||
7d9e447a HL |
13 | #define SSL_CONN_CLOSE_FLAG_LOCAL |
14 | #define SSL_CONN_CLOSE_FLAG_TRANSPORT | |
15 | ||
1e4a9d88 HL |
16 | typedef struct ssl_conn_close_info_st { |
17 | uint64_t error_code; | |
18 | char *reason; | |
19 | size_t reason_len; | |
7d9e447a | 20 | uint32_t flags; |
1e4a9d88 HL |
21 | } SSL_CONN_CLOSE_INFO; |
22 | ||
23 | int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info, | |
24 | size_t info_len); | |
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
28 | The SSL_get_conn_close_info() function provides information about why and how a | |
29 | QUIC connection was closed. | |
30 | ||
5fc256cd HL |
31 | Connection closure information is written to I<*info>, which must be non-NULL. |
32 | I<info_len> must be set to C<sizeof(*info)>. | |
1e4a9d88 HL |
33 | |
34 | The following fields are set: | |
35 | ||
36 | =over 4 | |
37 | ||
5fc256cd | 38 | =item I<error_code> |
1e4a9d88 HL |
39 | |
40 | This is a 62-bit QUIC error code. It is either a 62-bit application error code | |
7d9e447a HL |
41 | (if B<SSL_CONN_CLOSE_FLAG_TRANSPORT> not set in I<flags>) or a 62-bit standard |
42 | QUIC transport error code (if B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is set in | |
43 | I<flags>). | |
1e4a9d88 | 44 | |
5fc256cd | 45 | =item I<reason> |
1e4a9d88 HL |
46 | |
47 | If non-NULL, this is intended to be a UTF-8 textual string briefly describing | |
48 | the reason for connection closure. The length of the reason string in bytes is | |
5fc256cd | 49 | given in I<reason_len>. While, if non-NULL, OpenSSL guarantees that this string |
1e4a9d88 HL |
50 | will be zero terminated, consider that this buffer may originate from the |
51 | (untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use | |
5fc256cd | 52 | of I<reason_len> is recommended. |
1e4a9d88 HL |
53 | |
54 | While it is intended as per the QUIC protocol that this be a UTF-8 string, there | |
55 | is no guarantee that this is the case for strings received from the peer. | |
56 | ||
7d9e447a | 57 | =item B<SSL_CONN_CLOSE_FLAG_LOCAL> |
1e4a9d88 | 58 | |
7d9e447a HL |
59 | If I<flags> has B<SSL_CONN_CLOSE_FLAG_LOCAL> set, connection closure was locally |
60 | triggered. This could be due to an application request (e.g. if | |
61 | B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is unset), or (if | |
62 | I<SSL_CONN_CLOSE_FLAG_TRANSPORT> is set) due to logic internal to the QUIC | |
63 | implementation (for example, if the peer engages in a protocol violation, or an | |
64 | idle timeout occurs). | |
1e4a9d88 | 65 | |
7d9e447a | 66 | If unset, connection closure was remotely triggered. |
1e4a9d88 | 67 | |
7d9e447a | 68 | =item B<SSL_CONN_CLOSE_FLAG_TRANSPORT> |
1e4a9d88 | 69 | |
7d9e447a HL |
70 | If I<flags> has B<SSL_CONN_CLOSE_FLAG_TRANSPORT> set, connection closure was |
71 | triggered for QUIC protocol reasons. Otherwise, connection closure was triggered | |
72 | by the local or remote application. | |
1e4a9d88 HL |
73 | |
74 | =back | |
75 | ||
76 | =head1 RETURN VALUES | |
77 | ||
78 | SSL_get_conn_close_info() returns 1 on success and 0 on failure. This function | |
79 | fails if called on a QUIC connection SSL object which has not yet been | |
80 | terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC | |
81 | SSL object. | |
82 | ||
83 | =head1 SEE ALSO | |
84 | ||
85 | L<SSL_shutdown_ex(3)> | |
86 | ||
87 | =head1 HISTORY | |
88 | ||
89 | This function was added in OpenSSL 3.2. | |
90 | ||
91 | =head1 COPYRIGHT | |
92 | ||
93 | Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. | |
94 | ||
95 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
96 | this file except in compliance with the License. You can obtain a copy | |
97 | in the file LICENSE in the source distribution or at | |
98 | L<https://www.openssl.org/source/license.html>. | |
99 | ||
100 | =cut |