QUIC: Rename SSL_set_initial_peer_addr to SSL_set1_initial_peer_addr

Fixes #21701

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21814)

diff --git a/apps/s_client.c b/apps/s_client.c
index a6c5a559a9da720fd35ad2b89f225dbd605a6bc1..5577a9e903866016d74fbdd8d1210ca655623de6 100644 (file)
--- a/apps/s_client.c
+++ b/apps/s_client.c
@@ -2252,7 +2252,7 @@ int s_client_main(int argc, char **argv)
 #ifndef OPENSSL_NO_QUIC
     if (isquic) {
         sbio = BIO_new_dgram(sock, BIO_NOCLOSE);
-        if (!SSL_set_initial_peer_addr(con, peer_addr)) {
+        if (!SSL_set1_initial_peer_addr(con, peer_addr)) {
             BIO_printf(bio_err, "Failed to set the initial peer address\n");
             goto shut;
         }

diff --git a/demos/guide/quic-client-block.c b/demos/guide/quic-client-block.c
index 54d6a0bf3764bc6425fac716b3160e6c350da532..cbe6deb7c11e2b5a232615ff4fcb46668216b00b 100644 (file)
--- a/demos/guide/quic-client-block.c
+++ b/demos/guide/quic-client-block.c
@@ -202,7 +202,7 @@ int main(void)
         goto end;
     }
 
-    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;
     }

diff --git a/doc/build.info b/doc/build.info
index 829fe556823ec4188688e16d5e2563d62567dee3..958bbd0d1a07ba1ace432d29f473af896c215e29 100644 (file)
--- 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 6ff536b845f152dc2ce62b30ffb46b6fcee3ad82..52e199cee6fff8c54696f7cd33882b3776c9e47e 100644 (file)
--- 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 332293716db89cac299c1fbbd499c7387e8de9ce..ab1c81e2f1c13c7becbb0886b124b04cf0f17b0c 100644 (file)
--- 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_set_initial_peer_addr.pod b/doc/man3/SSL_set1_initial_peer_addr.pod
similarity index 72%
rename from doc/man3/SSL_set_initial_peer_addr.pod
rename to doc/man3/SSL_set1_initial_peer_addr.pod
index acb4ef22c05d99d5b83ba9a65bf484cc73749e8f..d1cdeb0234e6f1ae3c145cdf787027a4d8a389b7 100644 (file)
--- a/doc/man3/SSL_set_initial_peer_addr.pod
+++ b/doc/man3/SSL_set1_initial_peer_addr.pod
@@ -2,17 +2,17 @@
 
 =head1 NAME
 
-SSL_set_initial_peer_addr - set the initial peer address for a QUIC connection
+SSL_set1_initial_peer_addr - set the initial peer address for a QUIC connection
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
- int SSL_set_initial_peer_addr(SSL *s, const BIO_ADDR *addr);
+ int SSL_set1_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
+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<addr> must point to a B<BIO_ADDR>
@@ -24,15 +24,19 @@ destination peer address can be detected automatically; if
 B<BIO_CTRL_DGRAM_GET_PEER> returns a valid (non-B<AF_UNSPEC>) 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.
+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_set_initial_peer_addr() configures the destination address used for initial
+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<BIO_ADDR>
+structure pointed to by I<addr> may be freed by the caller after this function
+returns.
+
 =head1 RETURN VALUES
 
 Returns 1 on success and 0 on failure.
@@ -43,7 +47,7 @@ L<BIO_ADDR(3)>, L<ssl(7)>
 
 =head1 HISTORY
 
-The SSL_set_initial_peer_addr() function was added in OpenSSL 3.2.
+The SSL_set1_initial_peer_addr() function was added in OpenSSL 3.2.
 
 =head1 COPYRIGHT
 

diff --git a/doc/man7/openssl-quic.pod b/doc/man7/openssl-quic.pod
index 6f3ee00f4e24686c66f80c4e5b5141bb6c859d7d..2ecf488d0618a73faa6e174f64346077cd177a41 100644 (file)
--- 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<BIO_s_datagram(3)> instead when
 using QUIC. The socket must be configured in nonblocking mode. You may or may
-not need to use L<SSL_set_initial_peer_addr(3)> to set the initial peer address;
-see the B<QUIC-SPECIFIC APIS> section for details.
+not need to use L<SSL_set1_initial_peer_addr(3)> to set the initial peer
+address; see the B<QUIC-SPECIFIC APIS> section for details.
 
 =item
 
@@ -548,12 +548,12 @@ conjunction with L<SSL_get_rpoll_descriptor(3)> and
 L<SSL_get_wpoll_descriptor(3)> respectively. They determine whether the
 respective poll descriptor is currently relevant for the purposes of polling.
 
-=item L<SSL_set_initial_peer_addr(3)>
+=item L<SSL_set1_initial_peer_addr(3)>
 
 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<SSL_set_initial_peer_addr(3)> for details.
+autodetected in some cases. See L<SSL_set1_initial_peer_addr(3)> for details.
 
 =item L<SSL_shutdown_ex(3)>
 
@@ -747,7 +747,7 @@ L<SSL_set_blocking_mode(3)>.
 =item
 
 It should configure the SSL object as desired, set an initial peer as needed
-using L<SSL_set_initial_peer_addr(3)>, and trigger the connection process by
+using L<SSL_set1_initial_peer_addr(3)>, and trigger the connection process by
 calling L<SSL_connect(3)>.
 
 =item
@@ -823,7 +823,7 @@ L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>,
 L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)>,
 L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>,
 L<SSL_set_blocking_mode(3)>, L<SSL_shutdown_ex(3)>,
-L<SSL_set_initial_peer_addr(3)>, L<SSL_stream_conclude(3)>,
+L<SSL_set1_initial_peer_addr(3)>, L<SSL_stream_conclude(3)>,
 L<SSL_stream_reset(3)>, L<SSL_get_stream_read_state(3)>,
 L<SSL_get_stream_read_error_code(3)>, L<SSL_get_conn_close_info(3)>,
 L<SSL_get0_connection(3)>, L<SSL_get_stream_type(3)>, L<SSL_get_stream_id(3)>,

diff --git a/doc/man7/ossl-guide-quic-client-block.pod b/doc/man7/ossl-guide-quic-client-block.pod
index 437c57b68a29a84d736da9b8971b92b4fc4f7275..a9826d5145f01534a43053972df0176d25528470 100644 (file)
--- a/doc/man7/ossl-guide-quic-client-block.pod
+++ b/doc/man7/ossl-guide-quic-client-block.pod
@@ -219,9 +219,9 @@ L<SSL_set_alpn_protos(3)> 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</Creating the socket and BIO> above we saved that
 address away for future use. Now we need to use it via the
-L<SSL_set_initial_peer_addr(3)> function.
+L<SSL_set1_initial_peer_addr(3)> 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;
     }

diff --git a/include/openssl/ssl.h.in b/include/openssl/ssl.h.in
index 66ebaa4784a54384ce408020aabb6fdeabc63029..1738d97021c41dcd228973015994f0edf7ccbfc0 100644 (file)
--- a/include/openssl/ssl.h.in
+++ b/include/openssl/ssl.h.in
@@ -2267,7 +2267,7 @@ __owur int SSL_net_read_desired(SSL *s);
 __owur int SSL_net_write_desired(SSL *s);
 __owur int SSL_set_blocking_mode(SSL *s, int blocking);
 __owur int SSL_get_blocking_mode(SSL *s);
-__owur int SSL_set_initial_peer_addr(SSL *s, const BIO_ADDR *peer_addr);
+__owur int SSL_set1_initial_peer_addr(SSL *s, const BIO_ADDR *peer_addr);
 __owur SSL *SSL_get0_connection(SSL *s);
 __owur int SSL_is_connection(SSL *s);
 

diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index c3a7882a5b113aa71c5bdc773dbccbe034cc4edb..bda6a9c7beef2c44a2538a760bf46ea10c54a197 100644 (file)
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -7365,7 +7365,7 @@ int SSL_get_blocking_mode(SSL *s)
 #endif
 }
 
-int SSL_set_initial_peer_addr(SSL *s, const BIO_ADDR *peer_addr)
+int SSL_set1_initial_peer_addr(SSL *s, const BIO_ADDR *peer_addr)
 {
 #ifndef OPENSSL_NO_QUIC
     if (!IS_QUIC(s))

diff --git a/test/helpers/quictestlib.c b/test/helpers/quictestlib.c
index 1b204658bfbf54fc1eec7d5cf4e6c6a7b638f492..2dbbb435bbabb9ff24800c1e3124faeb9a45bab4 100644 (file)
--- a/test/helpers/quictestlib.c
+++ b/test/helpers/quictestlib.c
@@ -146,7 +146,7 @@ int qtest_create_quic_objects(OSSL_LIB_CTX *libctx, SSL_CTX *clientctx,
                                          (flags & QTEST_FLAG_BLOCK) != 0 ? 1 : 0)))
         goto err;
 
-    if (!TEST_true(SSL_set_initial_peer_addr(*cssl, peeraddr)))
+    if (!TEST_true(SSL_set1_initial_peer_addr(*cssl, peeraddr)))
         goto err;
 
     if (fault != NULL) {

diff --git a/util/libssl.num b/util/libssl.num
index 91320fe2e59c3981b10a0db467b35d3459fd3be8..1cb0558ac6b4c17644ee080a546526e5f4db9133 100644 (file)
--- a/util/libssl.num
+++ b/util/libssl.num
@@ -535,7 +535,7 @@ SSL_get_rpoll_descriptor                ?   3_2_0   EXIST::FUNCTION:
 SSL_get_wpoll_descriptor                ?      3_2_0   EXIST::FUNCTION:
 SSL_set_blocking_mode                   ?      3_2_0   EXIST::FUNCTION:
 SSL_get_blocking_mode                   ?      3_2_0   EXIST::FUNCTION:
-SSL_set_initial_peer_addr               ?      3_2_0   EXIST::FUNCTION:
+SSL_set1_initial_peer_addr              ?      3_2_0   EXIST::FUNCTION:
 SSL_net_read_desired                    ?      3_2_0   EXIST::FUNCTION:
 SSL_net_write_desired                   ?      3_2_0   EXIST::FUNCTION:
 SSL_shutdown_ex                         ?      3_2_0   EXIST::FUNCTION: