QUIC API: Revise SSL_get_conn_close_info to use a flags field

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from #21905)

doc/designs/quic-design/quic-api.md

@@ -830,12 +830,14 @@ unidirectional stream), returns -1.
 | New       | Never         | No        | C             |
 
 ```c
+#define SSL_CONN_CLOSE_FLAG_LOCAL
+#define SSL_CONN_CLOSE_FLAG_TRANSPORT
+
 typedef struct ssl_conn_close_info_st {
     uint64_t error_code;
     char     *reason;
     size_t   reason_len;
-    int      is_local;
-    int      is_transport;
+    uint32_t flags;
 } SSL_CONN_CLOSE_INFO;
 
 int SSL_get_conn_close_info(SSL *ssl,
@@ -854,11 +856,12 @@ always be zero terminated, but since it is received from a potentially untrusted
 peer, may also contain zero bytes. `info->reason_len` is the true length of the
 reason string in bytes.
 
-`info->is_local` is 1 if the connection closure was locally initiated.
+`info->flags` has `SSL_CONN_CLOSE_FLAG_LOCAL` set if the connection closure was
+locally initiated.
 
-`info->is_transport` is 1 if the connection closure was initiated by QUIC, and 0
-if it was initiated by the application. The namespace of `info->error_code` is
-determined by this parameter.
+`info->flags` has `SSL_CONN_CLOSE_FLAG_TRANSPORT` if the connection closure was
+initiated by QUIC, and 0 if it was initiated by the application. The namespace
+of `info->error_code` is determined by this parameter.
 
 ### New APIs for Multi-Stream Operation
 

doc/man3/SSL_get_conn_close_info.pod

@@ -2,18 +2,22 @@
 
 =head1 NAME
 
-SSL_get_conn_close_info - get information about why a QUIC connection was closed
+SSL_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL,
+SSL_CONN_CLOSE_FLAG_TRANSPORT - get information about why a QUIC connection was
+closed
 
 =head1 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;
      char     *reason;
      size_t   reason_len;
-     int      is_local;
-     int      is_transport;
+     uint32_t flags;
  } SSL_CONN_CLOSE_INFO;
 
  int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info,
@@ -34,8 +38,9 @@ The following fields are set:
 =item I<error_code>
 
 This is a 62-bit QUIC error code. It is either a 62-bit application error code
-(if I<is_transport> is 0) or a  62-bit standard QUIC transport error code (if
-I<is_transport> is 1).
+(if B<SSL_CONN_CLOSE_FLAG_TRANSPORT> not set in I<flags>) or a  62-bit standard
+QUIC transport error code (if B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is set in
+I<flags>).
 
 =item I<reason>
 
@@ -49,20 +54,22 @@ of I<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.
 
-=item I<is_local>
-
-If 1, connection closure was locally triggered. This could be due to an
-application request (e.g. if I<is_transport> is 0), or (if I<is_transport> is 1)
-due to logic internal to the QUIC implementation (for example, if the peer
-engages in a protocol violation, or an idle timeout occurs).
+=item B<SSL_CONN_CLOSE_FLAG_LOCAL>
 
-If 0, connection closure was remotely triggered.
+If I<flags> has B<SSL_CONN_CLOSE_FLAG_LOCAL> set, connection closure was locally
+triggered. This could be due to an application request (e.g. if
+B<SSL_CONN_CLOSE_FLAG_TRANSPORT> is unset), or (if
+I<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).
 
-=item I<is_transport>
+If unset, connection closure was remotely triggered.
 
-If 1, connection closure was triggered for QUIC protocol reasons.
+=item B<SSL_CONN_CLOSE_FLAG_TRANSPORT>
 
-If 0, connection closure was triggered by the local or remote application.
+If I<flags> has B<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.
 
 =back
 

include/openssl/ssl.h.in

@@ -2343,11 +2343,14 @@ __owur int SSL_get_stream_write_state(SSL *ssl);
 __owur int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
 __owur int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);
 
+#define SSL_CONN_CLOSE_FLAG_LOCAL       (1U << 0)
+#define SSL_CONN_CLOSE_FLAG_TRANSPORT   (1U << 1)
+
 typedef struct ssl_conn_close_info_st {
     uint64_t    error_code;
     const char  *reason;
     size_t      reason_len;
-    int         is_local, is_transport;
+    uint32_t    flags;
 } SSL_CONN_CLOSE_INFO;
 
 __owur int SSL_get_conn_close_info(SSL *ssl,

ssl/quic/quic_impl.c

@@ -3341,8 +3341,11 @@ int ossl_quic_get_conn_close_info(SSL *ssl,
     info->error_code    = tc->error_code;
     info->reason        = tc->reason;
     info->reason_len    = tc->reason_len;
-    info->is_local      = !tc->remote;
-    info->is_transport  = !tc->app;
+    info->flags         = 0;
+    if (!tc->remote)
+       info->flags |= SSL_CONN_CLOSE_FLAG_LOCAL;
+    if (!tc->app)
+        info->flags |= SSL_CONN_CLOSE_FLAG_TRANSPORT;
     return 1;
 }
 

test/quic_multistream_test.c

@@ -1385,8 +1385,12 @@ static int run_script_worker(struct helper *h, const struct script_op *script,
                 if (!SSL_get_conn_close_info(c_tgt, &cc_info, sizeof(cc_info)))
                     SPIN_AGAIN();
 
-                if (!TEST_int_eq(expect_app, !cc_info.is_transport)
-                    || !TEST_int_eq(expect_remote, !cc_info.is_local)
+                if (!TEST_int_eq(expect_app,
+                                 (cc_info.flags
+                                  & SSL_CONN_CLOSE_FLAG_TRANSPORT) == 0)
+                    || !TEST_int_eq(expect_remote,
+                                    (cc_info.flags
+                                     & SSL_CONN_CLOSE_FLAG_LOCAL) == 0)
                     || !TEST_uint64_t_eq(error_code, cc_info.error_code))
                     goto out;
             }

util/other.syms

@@ -647,6 +647,8 @@ SSL_want_read                           define
 SSL_want_retry_verify                   define
 SSL_want_write                          define
 SSL_want_x509_lookup                    define
+SSL_CONN_CLOSE_FLAG_LOCAL               define
+SSL_CONN_CLOSE_FLAG_TRANSPORT           define
 SSLv23_client_method                    define
 SSLv23_method                           define
 SSLv23_server_method                    define