diff options
author | Hugo Landau <hlandau@openssl.org> | 2023-08-30 13:41:39 +0100 |
---|---|---|
committer | Hugo Landau <hlandau@openssl.org> | 2023-09-01 14:02:50 +0100 |
commit | 7d9e447ab812df34bba581c5918721cc704fdacb (patch) | |
tree | e14a4894274d427d184468fe9fe19311abfa62d7 /doc | |
parent | cc50b44e555d71a10cdc45588d1b57523fb95ee4 (diff) |
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 https://github.com/openssl/openssl/pull/21905)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/designs/quic-design/quic-api.md | 15 | ||||
-rw-r--r-- | doc/man3/SSL_get_conn_close_info.pod | 37 |
2 files changed, 31 insertions, 21 deletions
diff --git a/doc/designs/quic-design/quic-api.md b/doc/designs/quic-design/quic-api.md index ab1c81e2f1..3684c95880 100644 --- a/doc/designs/quic-design/quic-api.md +++ b/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 diff --git a/doc/man3/SSL_get_conn_close_info.pod b/doc/man3/SSL_get_conn_close_info.pod index 4d5da74b75..b82e434f2b 100644 --- a/doc/man3/SSL_get_conn_close_info.pod +++ b/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 |