doc/man3/SSL_get_conn_close_info.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL,
   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,
  26 OSSL_QUIC_ERR_CRYPTO_ERR,
  27 OSSL_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
  75 The SSL_get_conn_close_info() function provides information about why and how a
  76 QUIC connection was closed.
  77
  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)>.
  80
  81 The following fields are set:
  82
  83 =over 4
  84
  85 =item I<error_code>
  86
  87 This 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
  89 QUIC transport error code (if B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is set in
  90 I<flags>).
  91
  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
  99 =item I<reason>
 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
 103 given in I<reason_len>. While, if non-NULL, OpenSSL guarantees that this string
 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
 106 of I<reason_len> is recommended.
 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
 111 =item B<SSL_CONN_CLOSE_FLAG_LOCAL>
 112
 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).
 119
 120 If unset, connection closure was remotely triggered.
 121
 122 =item B<SSL_CONN_CLOSE_FLAG_TRANSPORT>
 123
 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.
 127
 128 =back
 129
 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
 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
 170 Copyright 2002-2024 The OpenSSL Project Authors. All Rights Reserved.
 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