SSL_GET_CONN_CLOSE_INFO(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 SSL_GET_CONN_CLOSE_INFO 💖 (that's the manual name, bestie, section 3ossl)

okay so. your QUIC connection just ✨ended✨ and you're sitting there like… why. what happened. who did this. bestie, this page is FOR YOU. it's the whole "get information about why a QUIC connection was closed" situation and honestly? iconic. 🔥

🌸 NAME 🌸

SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL, SSL_CONN_CLOSE_FLAG_TRANSPORT, OSSL_QUIC_ERR_NO_ERROR, OSSL_QUIC_ERR_INTERNAL_ERROR, OSSL_QUIC_ERR_CONNECTION_REFUSED, OSSL_QUIC_ERR_FLOW_CONTROL_ERROR, OSSL_QUIC_ERR_STREAM_LIMIT_ERROR, OSSL_QUIC_ERR_STREAM_STATE_ERROR, OSSL_QUIC_ERR_FINAL_SIZE_ERROR, OSSL_QUIC_ERR_FRAME_ENCODING_ERROR, OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR, OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR, OSSL_QUIC_ERR_PROTOCOL_VIOLATION, OSSL_QUIC_ERR_INVALID_TOKEN, OSSL_QUIC_ERR_APPLICATION_ERROR, OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED, OSSL_QUIC_ERR_KEY_UPDATE_ERROR, OSSL_QUIC_ERR_AEAD_LIMIT_REACHED, OSSL_QUIC_ERR_NO_VIABLE_PATH, OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN, OSSL_QUIC_ERR_CRYPTO_ERR_END, OSSL_QUIC_ERR_CRYPTO_ERR, OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT — get information about why a QUIC connection was closed 💅

like. the whole point. the gossip. the receipts. 🧚

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

#define OSSL_QUIC_ERR_NO_ERROR                  0x00
#define OSSL_QUIC_ERR_INTERNAL_ERROR            0x01
#define OSSL_QUIC_ERR_CONNECTION_REFUSED        0x02
#define OSSL_QUIC_ERR_FLOW_CONTROL_ERROR        0x03
#define OSSL_QUIC_ERR_STREAM_LIMIT_ERROR        0x04
#define OSSL_QUIC_ERR_STREAM_STATE_ERROR        0x05
#define OSSL_QUIC_ERR_FINAL_SIZE_ERROR          0x06
#define OSSL_QUIC_ERR_FRAME_ENCODING_ERROR      0x07
#define OSSL_QUIC_ERR_TRANSPORT_PARAMETER_ERROR 0x08
#define OSSL_QUIC_ERR_CONNECTION_ID_LIMIT_ERROR 0x09
#define OSSL_QUIC_ERR_PROTOCOL_VIOLATION        0x0A
#define OSSL_QUIC_ERR_INVALID_TOKEN             0x0B
#define OSSL_QUIC_ERR_APPLICATION_ERROR         0x0C
#define OSSL_QUIC_ERR_CRYPTO_BUFFER_EXCEEDED    0x0D
#define OSSL_QUIC_ERR_KEY_UPDATE_ERROR          0x0E
#define OSSL_QUIC_ERR_AEAD_LIMIT_REACHED        0x0F
#define OSSL_QUIC_ERR_NO_VIABLE_PATH            0x10

/* Inclusive range for handshake-specific errors. */
#define OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN          0x0100
#define OSSL_QUIC_ERR_CRYPTO_ERR_END            0x01FF

#define OSSL_QUIC_ERR_CRYPTO_ERR(X)

#define OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT

copy it exactly, bestie, don't freestyle. 🙈

🦋 DESCRIPTION 🦋

so SSL_get_conn_close_info() is the function that spills the tea ☕ about why and how a QUIC connection was closed. it's giving detective energy, fr fr.

the closure info gets written into *info, and *info MUST be non-NULL. like, mandatory mandatory. and info_len has to be set to sizeof(*info). no cap.

here's the fields it sets, one by one, because we're thorough like that 💅

🌟 the fields

  • error_code — this is a 62-bit QUIC error code. it's either a 62-bit application error code (if SSL_CONN_CLOSE_FLAG_TRANSPORT is not set in flags) or a 62-bit standard QUIC transport error code (if SSL_CONN_CLOSE_FLAG_TRANSPORT is set in flags). two moods, one field.
  • frame_type — if SSL_CONN_CLOSE_FLAG_TRANSPORT is set, this may be set to a QUIC frame type number that caused the connection to be closed. it may also be set to 0 if no frame type was specified as causing the closure. if SSL_CONN_CLOSE_FLAG_TRANSPORT is not set, this is set to 0. simple as that.
  • 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. and listen: while, if non-NULL, OpenSSL guarantees this string will be zero terminated, please consider that this buffer may originate from the (untrusted) peer and thus may also contain zero bytes elsewhere. so use reason_len, bestie, seriously. 🙏

also — 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. the peer is not your friend here, okay? trust issues are valid. 💀

  • SSL_CONN_CLOSE_FLAG_LOCAL — if flags has SSL_CONN_CLOSE_FLAG_LOCAL set, the connection closure was locally triggered. this could be because of 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. messy of them, honestly.

if unset, the connection closure was remotely triggered. so it was them, not you. 👑

  • SSL_CONN_CLOSE_FLAG_TRANSPORT — if flags has SSL_CONN_CLOSE_FLAG_TRANSPORT set, the connection closure was triggered for QUIC protocol reasons. otherwise, the connection closure was triggered by the local or remote application.

🌈 the error code macros

the OSSL_QUIC_ERR macro definitions provide the QUIC transport error codes as defined by RFC 9000. 📜

the OSSL_QUIC_ERR_CRYPTO_ERR() macro can be used to convert a TLS alert code into a QUIC transport error code by mapping it into the range reserved for such codes by RFC 9000. that range begins at OSSL_QUIC_ERR_CRYPTO_ERR_BEGIN and ends at OSSL_QUIC_ERR_CRYPTO_ERR_END, inclusive. glow-up for your error codes, lowkey. ✨

🎀 NON-STANDARD TRANSPORT ERROR CODES 🎀

some conditions that can cause QUIC connection termination are not signalled on the wire and therefore do not have standard error codes. OpenSSL indicates these errors via SSL_get_conn_close_info() by setting SSL_CONN_CLOSE_FLAG_TRANSPORT and using one of the following error values. these codes are specific to OpenSSL, and cannot be sent over the wire, as they are above 2**62. so they're homegrown. exclusive. iykyk. 🫶

  • OSSL_QUIC_LOCAL_ERR_IDLE_TIMEOUT — the connection was terminated immediately due to the idle timeout expiring. yeah. it just… left. no text back. 😭

💫 RETURN VALUES 💫

SSL_get_conn_close_info() returns 1 on success and 0 on failure. slay when it's 1.

and it fails if you call it on a QUIC connection SSL object which has not yet been terminated — like, bestie, nothing has happened yet, there's nothing to report. it also fails if you call it on a QUIC stream SSL object or a non-QUIC SSL object. wrong audience. 🙈

👑 SEE ALSO 👑

SSL_shutdown_ex(3) — go read that one next, it's in the same friend group. 🦋

⭐ HISTORY ⭐

this function was added in OpenSSL 3.2. so it's a newer baddie. ✨

Copyright 2002-2024 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>.

okay that's the whole page, no notes, ate and left no crumbs 💅

version 3.5.9, dated 2026-09-29, and yes this is SSL_GET_CONN_CLOSE_INFO(3ossl) signing off — mwah, go close some connections responsibly 🎀💖✨

📦 where this page comes from