1=pod
2
3=head1 NAME
4
5SSL_set1_initial_peer_addr - set the initial peer address for a QUIC connection
6
7=head1 SYNOPSIS
8
9 #include <openssl/ssl.h>
10
11 int SSL_set1_initial_peer_addr(SSL *s, const BIO_ADDR *addr);
12
13=head1 DESCRIPTION
14
15SSL_set1_initial_peer_addr() sets the initial destination peer address to be used
16for the purposes of establishing a QUIC connection in client mode. This function
17can be used only on a QUIC connection SSL object, and can be used only before a
18connection attempt is first made. I<addr> must point to a B<BIO_ADDR>
19representing a UDP destination address of the server to connect to.
20
21Where a QUIC connection object is provided with a write BIO which supports the
22B<BIO_CTRL_DGRAM_GET_PEER> control (for example, B<BIO_s_dgram>), the initial
23destination peer address can be detected automatically; if
24B<BIO_CTRL_DGRAM_GET_PEER> returns a valid (non-B<AF_UNSPEC>) peer address and
25no valid peer address has yet been set, this will be set automatically as the
26initial peer address. This behaviour can be overridden by calling
27SSL_set1_initial_peer_addr() with a valid peer address explicitly.
28
29The destination address used by QUIC may change over time in response to
30connection events, such as connection migration (where supported).
31SSL_set1_initial_peer_addr() configures the destination address used for initial
32connection establishment, and does not confer any guarantee about the
33destination address being used for communication at any later time in the
34connection lifecycle.
35
36This function makes a copy of the address passed by the caller; the B<BIO_ADDR>
37structure pointed to by I<addr> may be freed by the caller after this function
38returns.
39
40=head1 RETURN VALUES
41
42Returns 1 on success and 0 on failure.
43
44=head1 SEE ALSO
45
46L<BIO_ADDR(3)>, L<ssl(7)>
47
48=head1 HISTORY
49
50The SSL_set1_initial_peer_addr() function was added in OpenSSL 3.2.
51
52=head1 COPYRIGHT
53
54Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
55
56Licensed under the Apache License 2.0 (the "License").  You may not use
57this file except in compliance with the License.  You can obtain a copy
58in the file LICENSE in the source distribution or at
59L<https://www.openssl.org/source/license.html>.
60
61=cut
62