From ce7a9e23fb1ea249e08c3dfa9c9f701a701f2719 Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Wed, 23 Aug 2023 08:19:01 +0100 Subject: QUIC: Rename SSL_set_initial_peer_addr to SSL_set1_initial_peer_addr Fixes #21701 Reviewed-by: Tomas Mraz Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/21814) --- doc/build.info | 12 +++--- doc/designs/quic-design/quic-api-ssl-funcs.md | 3 +- doc/designs/quic-design/quic-api.md | 8 ++-- doc/man3/SSL_set1_initial_peer_addr.pod | 61 +++++++++++++++++++++++++++ doc/man3/SSL_set_initial_peer_addr.pod | 57 ------------------------- doc/man7/openssl-quic.pod | 12 +++--- doc/man7/ossl-guide-quic-client-block.pod | 4 +- 7 files changed, 80 insertions(+), 77 deletions(-) create mode 100644 doc/man3/SSL_set1_initial_peer_addr.pod delete mode 100644 doc/man3/SSL_set_initial_peer_addr.pod (limited to 'doc') diff --git a/doc/build.info b/doc/build.info index 829fe55682..958bbd0d1a 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2675,6 +2675,10 @@ DEPEND[html/man3/SSL_set1_host.html]=man3/SSL_set1_host.pod GENERATE[html/man3/SSL_set1_host.html]=man3/SSL_set1_host.pod DEPEND[man/man3/SSL_set1_host.3]=man3/SSL_set1_host.pod GENERATE[man/man3/SSL_set1_host.3]=man3/SSL_set1_host.pod +DEPEND[html/man3/SSL_set1_initial_peer_addr.html]=man3/SSL_set1_initial_peer_addr.pod +GENERATE[html/man3/SSL_set1_initial_peer_addr.html]=man3/SSL_set1_initial_peer_addr.pod +DEPEND[man/man3/SSL_set1_initial_peer_addr.3]=man3/SSL_set1_initial_peer_addr.pod +GENERATE[man/man3/SSL_set1_initial_peer_addr.3]=man3/SSL_set1_initial_peer_addr.pod DEPEND[html/man3/SSL_set1_server_cert_type.html]=man3/SSL_set1_server_cert_type.pod GENERATE[html/man3/SSL_set1_server_cert_type.html]=man3/SSL_set1_server_cert_type.pod DEPEND[man/man3/SSL_set1_server_cert_type.3]=man3/SSL_set1_server_cert_type.pod @@ -2707,10 +2711,6 @@ DEPEND[html/man3/SSL_set_incoming_stream_policy.html]=man3/SSL_set_incoming_stre GENERATE[html/man3/SSL_set_incoming_stream_policy.html]=man3/SSL_set_incoming_stream_policy.pod DEPEND[man/man3/SSL_set_incoming_stream_policy.3]=man3/SSL_set_incoming_stream_policy.pod GENERATE[man/man3/SSL_set_incoming_stream_policy.3]=man3/SSL_set_incoming_stream_policy.pod -DEPEND[html/man3/SSL_set_initial_peer_addr.html]=man3/SSL_set_initial_peer_addr.pod -GENERATE[html/man3/SSL_set_initial_peer_addr.html]=man3/SSL_set_initial_peer_addr.pod -DEPEND[man/man3/SSL_set_initial_peer_addr.3]=man3/SSL_set_initial_peer_addr.pod -GENERATE[man/man3/SSL_set_initial_peer_addr.3]=man3/SSL_set_initial_peer_addr.pod DEPEND[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod GENERATE[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod DEPEND[man/man3/SSL_set_retry_verify.3]=man3/SSL_set_retry_verify.pod @@ -3576,6 +3576,7 @@ html/man3/SSL_read_early_data.html \ html/man3/SSL_rstate_string.html \ html/man3/SSL_session_reused.html \ html/man3/SSL_set1_host.html \ +html/man3/SSL_set1_initial_peer_addr.html \ html/man3/SSL_set1_server_cert_type.html \ html/man3/SSL_set_async_callback.html \ html/man3/SSL_set_bio.html \ @@ -3584,7 +3585,6 @@ html/man3/SSL_set_connect_state.html \ html/man3/SSL_set_default_stream_mode.html \ html/man3/SSL_set_fd.html \ html/man3/SSL_set_incoming_stream_policy.html \ -html/man3/SSL_set_initial_peer_addr.html \ html/man3/SSL_set_retry_verify.html \ html/man3/SSL_set_session.html \ html/man3/SSL_set_shutdown.html \ @@ -4215,6 +4215,7 @@ man/man3/SSL_read_early_data.3 \ man/man3/SSL_rstate_string.3 \ man/man3/SSL_session_reused.3 \ man/man3/SSL_set1_host.3 \ +man/man3/SSL_set1_initial_peer_addr.3 \ man/man3/SSL_set1_server_cert_type.3 \ man/man3/SSL_set_async_callback.3 \ man/man3/SSL_set_bio.3 \ @@ -4223,7 +4224,6 @@ man/man3/SSL_set_connect_state.3 \ man/man3/SSL_set_default_stream_mode.3 \ man/man3/SSL_set_fd.3 \ man/man3/SSL_set_incoming_stream_policy.3 \ -man/man3/SSL_set_initial_peer_addr.3 \ man/man3/SSL_set_retry_verify.3 \ man/man3/SSL_set_session.3 \ man/man3/SSL_set_shutdown.3 \ diff --git a/doc/designs/quic-design/quic-api-ssl-funcs.md b/doc/designs/quic-design/quic-api-ssl-funcs.md index 6ff536b845..52e199cee6 100644 --- a/doc/designs/quic-design/quic-api-ssl-funcs.md +++ b/doc/designs/quic-design/quic-api-ssl-funcs.md @@ -629,8 +629,7 @@ Notes: | `SSL_get_wpoll_descriptor` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟢Done | | `SSL_want_net_read` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟢Done | | `SSL_want_net_write` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟢Done | -| `SSL_get_initial_peer_addr` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟢Done | -| `SSL_set_initial_peer_addr` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟢Done | +| `SSL_set1_initial_peer_addr` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟢Done | | `SSL_shutdown_ex` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟡TODO | | `SSL_stream_conclude` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟡TODO | | `SSL_stream_reset` | CSSM | 🟦N | 🟩A | 🟥QSA | 🟡TODO | diff --git a/doc/designs/quic-design/quic-api.md b/doc/designs/quic-design/quic-api.md index 332293716d..ab1c81e2f1 100644 --- a/doc/designs/quic-design/quic-api.md +++ b/doc/designs/quic-design/quic-api.md @@ -36,7 +36,7 @@ designs and the relevant design decisions. - [`SSL_get_rpoll_descriptor`, `SSL_get_wpoll_descriptor`](#-ssl-get-rpoll-descriptor----ssl-get-wpoll-descriptor-) - [`SSL_net_read_desired`, `SSL_net_write_desired`](#-ssl-want-net-read----ssl-want-net-write-) - [`SSL_want`, `SSL_want_read`, `SSL_want_write`](#-ssl-want----ssl-want-read----ssl-want-write-) - - [`SSL_set_initial_peer_addr`, `SSL_get_initial_peer_addr`](#-ssl-set-initial-peer-addr----ssl-get-initial-peer-addr-) + - [`SSL_set1_initial_peer_addr`](#-ssl-set-initial-peer-addr-) - [`SSL_shutdown_ex`](#-ssl-shutdown-ex-) - [`SSL_stream_conclude`](#-ssl-stream-conclude-) - [`SSL_stream_reset`](#-ssl-stream-reset-) @@ -519,20 +519,20 @@ write), not both. This call will not be implemented for QUIC (e.g. always returns `SSL_NOTHING`) and `SSL_net_read_desired` and `SSL_net_write_desired` will be used instead. -#### `SSL_set_initial_peer_addr`, `SSL_get_initial_peer_addr` +#### `SSL_set1_initial_peer_addr` | Semantics | `SSL_get_error` | Can Tick? | CSHL | | --------- | ------------- | --------- | ------------- | | New | Never | No | CS | -`SSL_set_initial_peer_addr` sets the initial L4 UDP peer address for an outgoing +`SSL_set1_initial_peer_addr` sets the initial L4 UDP peer address for an outgoing QUIC connection. The initial peer address may be autodetected if no peer address has already been set explicitly and the QUIC connection SSL object is provided with a `BIO_s_dgram` with a peer set. -`SSL_set_initial_peer_addr` cannot be called after a connection is established. +`SSL_set1_initial_peer_addr` cannot be called after a connection is established. #### `SSL_shutdown_ex` diff --git a/doc/man3/SSL_set1_initial_peer_addr.pod b/doc/man3/SSL_set1_initial_peer_addr.pod new file mode 100644 index 0000000000..d1cdeb0234 --- /dev/null +++ b/doc/man3/SSL_set1_initial_peer_addr.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_set1_initial_peer_addr - set the initial peer address for a QUIC connection + +=head1 SYNOPSIS + + #include + + int SSL_set1_initial_peer_addr(SSL *s, const BIO_ADDR *addr); + +=head1 DESCRIPTION + +SSL_set1_initial_peer_addr() sets the initial destination peer address to be used +for the purposes of establishing a QUIC connection in client mode. This function +can be used only on a QUIC connection SSL object, and can be used only before a +connection attempt is first made. I must point to a B +representing a UDP destination address of the server to connect to. + +Where a QUIC connection object is provided with a write BIO which supports the +B control (for example, B), the initial +destination peer address can be detected automatically; if +B returns a valid (non-B) peer address and +no valid peer address has yet been set, this will be set automatically as the +initial peer address. This behaviour can be overridden by calling +SSL_set1_initial_peer_addr() with a valid peer address explicitly. + +The destination address used by QUIC may change over time in response to +connection events, such as connection migration (where supported). +SSL_set1_initial_peer_addr() configures the destination address used for initial +connection establishment, and does not confer any guarantee about the +destination address being used for communication at any later time in the +connection lifecycle. + +This function makes a copy of the address passed by the caller; the B +structure pointed to by I may be freed by the caller after this function +returns. + +=head1 RETURN VALUES + +Returns 1 on success and 0 on failure. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The SSL_set1_initial_peer_addr() function was added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2022 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 +L. + +=cut diff --git a/doc/man3/SSL_set_initial_peer_addr.pod b/doc/man3/SSL_set_initial_peer_addr.pod deleted file mode 100644 index acb4ef22c0..0000000000 --- a/doc/man3/SSL_set_initial_peer_addr.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_initial_peer_addr - set the initial peer address for a QUIC connection - -=head1 SYNOPSIS - - #include - - int SSL_set_initial_peer_addr(SSL *s, const BIO_ADDR *addr); - -=head1 DESCRIPTION - -SSL_set_initial_peer_addr() sets the initial destination peer address to be used -for the purposes of establishing a QUIC connection in client mode. This function -can be used only on a QUIC connection SSL object, and can be used only before a -connection attempt is first made. I must point to a B -representing a UDP destination address of the server to connect to. - -Where a QUIC connection object is provided with a write BIO which supports the -B control (for example, B), the initial -destination peer address can be detected automatically; if -B returns a valid (non-B) peer address and -no valid peer address has yet been set, this will be set automatically as the -initial peer address. This behaviour can be overridden by calling -SSL_set_initial_peer_addr() with a valid peer address explicitly. - -The destination address used by QUIC may change over time in response to -connection events, such as connection migration (where supported). -SSL_set_initial_peer_addr() configures the destination address used for initial -connection establishment, and does not confer any guarantee about the -destination address being used for communication at any later time in the -connection lifecycle. - -=head1 RETURN VALUES - -Returns 1 on success and 0 on failure. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -The SSL_set_initial_peer_addr() function was added in OpenSSL 3.2. - -=head1 COPYRIGHT - -Copyright 2022 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 -L. - -=cut diff --git a/doc/man7/openssl-quic.pod b/doc/man7/openssl-quic.pod index 6f3ee00f4e..2ecf488d06 100644 --- a/doc/man7/openssl-quic.pod +++ b/doc/man7/openssl-quic.pod @@ -338,8 +338,8 @@ the SSL object to provide it with network access. Changes needed: Change your application to use L instead when using QUIC. The socket must be configured in nonblocking mode. You may or may -not need to use L to set the initial peer address; -see the B section for details. +not need to use L to set the initial peer +address; see the B section for details. =item @@ -548,12 +548,12 @@ conjunction with L and L respectively. They determine whether the respective poll descriptor is currently relevant for the purposes of polling. -=item L +=item L This function can be used to set the initial peer address for an outgoing QUIC connection. This function must be used in the general case when creating an outgoing QUIC connection; however, the correct initial peer address can be -autodetected in some cases. See L for details. +autodetected in some cases. See L for details. =item L @@ -747,7 +747,7 @@ L. =item It should configure the SSL object as desired, set an initial peer as needed -using L, and trigger the connection process by +using L, and trigger the connection process by calling L. =item @@ -823,7 +823,7 @@ L, L, L, L, L, L, L, L, -L, L, +L, L, L, L, L, L, L, L, L, diff --git a/doc/man7/ossl-guide-quic-client-block.pod b/doc/man7/ossl-guide-quic-client-block.pod index 437c57b68a..a9826d5145 100644 --- a/doc/man7/ossl-guide-quic-client-block.pod +++ b/doc/man7/ossl-guide-quic-client-block.pod @@ -219,9 +219,9 @@ L returns zero for success and nonzero for failure. An OpenSSL QUIC application must specify the target address of the server that is being connected to. In L above we saved that address away for future use. Now we need to use it via the -L function. +L function. - if (!SSL_set_initial_peer_addr(ssl, peer_addr)) { + if (!SSL_set1_initial_peer_addr(ssl, peer_addr)) { printf("Failed to set the initial peer address\n"); goto end; } -- cgit v1.2.3