NAME¶

SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL, SSL_CONN_CLOSE_FLAG_TRANSPORT - get information about why a QUIC connection was closed

SYNOPSIS¶

 #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);

DESCRIPTION¶

The SSL_get_conn_close_info() function provides information about why and how a QUIC connection was closed.

Connection closure information is written to *info, which must be non-NULL. info_len must be set to sizeof(*info).

The following fields are set:

error_code

This is a 62-bit QUIC error code. It is either a 62-bit application error code (if SSL_CONN_CLOSE_FLAG_TRANSPORT not set in flags) or a 62-bit standard QUIC transport error code (if SSL_CONN_CLOSE_FLAG_TRANSPORT is set in flags).

frame_type

If SSL_CONN_CLOSE_FLAG_TRANSPORT is set, this may be set to a QUIC 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 SSL_CONN_CLOSE_FLAG_TRANSPORT is not set, this is set to 0.

reason

If non-NULL, this is intended to be a UTF-8 textual string briefly describing the reason for connection closure. The length of the reason string in bytes is given in reason_len. 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 reason_len is recommended.

While it is intended as per the QUIC protocol that this be a UTF-8 string, there is no guarantee that this is the case for strings received from the peer.

SSL_CONN_CLOSE_FLAG_LOCAL

If flags has SSL_CONN_CLOSE_FLAG_LOCAL set, connection closure was locally triggered. This could be due to an application request (e.g. if SSL_CONN_CLOSE_FLAG_TRANSPORT is unset), or (if SSL_CONN_CLOSE_FLAG_TRANSPORT is set) due to logic internal to the QUIC implementation (for example, if the peer engages in a protocol violation, or an idle timeout occurs).

If unset, connection closure was remotely triggered.

SSL_CONN_CLOSE_FLAG_TRANSPORT

If flags has SSL_CONN_CLOSE_FLAG_TRANSPORT set, connection closure was triggered for QUIC protocol reasons. Otherwise, connection closure was triggered by the local or remote application.

RETURN VALUES¶

SSL_get_conn_close_info() returns 1 on success and 0 on failure. This function fails if called on a QUIC connection SSL object which has not yet been terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC SSL object.

SEE ALSO¶

SSL_shutdown_ex(3)

HISTORY¶

This function was added in OpenSSL 3.2.

COPYRIGHT¶

Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.