SSL_SET1_INITIAL_PEER_ADDR(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_set1_initial_peer_addr(3ossl) ✨

okay bestie, so this is a page from the OpenSSL manual — it's called SSL_SET1_INITIAL_PEER_ADDR and honestly it's giving "small function, big QUIC energy." Let's get into it 🫶

🌸 NAME 🌸

SSL_set1_initial_peer_addr — sets the initial peer address for a QUIC connection 💖

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

int SSL_set1_initial_peer_addr(SSL *s, const BIO_ADDR *addr);

🦋 DESCRIPTION 🦋

So SSL_set1_initial_peer_addr() sets the initial destination peer address — the one used for the purposes of establishing a QUIC connection in client mode. That's the whole vibe ✨

Real talk though, there's rules, and you gotta respect them:

  • This function can be used only on a QUIC connection SSL object.
  • It can be used only before a connection attempt is first made. Like, first-move-only, no takebacks, periodt 💀

addr must point to a BIO_ADDR representing a UDP destination address of the server to connect to 🎯

💫 the auto-detect situation 💫

Okay so, this is lowkey the cool part. Where a QUIC connection object is provided with a write BIO which supports the BIO_CTRL_DGRAM_GET_PEER control (for example, BIO_s_dgram), the initial destination peer address can be detected automatically 👑

Specifically: if BIO_CTRL_DGRAM_GET_PEER returns a valid (non-AF_UNSPEC) peer address and no valid peer address has yet been set, this will be set automatically as the initial peer address. Iconic, no cap 🎀

But — and this is the "not me overriding the vibes" moment — this behaviour can be overridden by calling SSL_set1_initial_peer_addr() with a valid peer address explicitly. So if you wanna be the main character, you absolutely can 🌈

🧚 the address may change, okay? 🧚

The destination address used by QUIC may change over time in response to connection events, such as connection migration (where supported). So don't get attached 💔

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. It's giving "starter address," not "forever address" 🙈

🍓 memory behaviour 🍓

This function makes a copy of the address passed by the caller; the BIO_ADDR structure pointed to by addr may be freed by the caller after this function returns. So you don't have to keep it alive — she's independent now 💅✨

🎀 RETURN VALUES 🎀

Returns 1 on success and 0 on failure. That's it, that's the whole mood 🫶

🔥 SEE ALSO 🔥

⭐ HISTORY ⭐

The SSL_set1_initial_peer_addr() function was added in OpenSSL 3.2. So if you're on something older, bestie, she is simply not there 😭

Copyright 2022-2023 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 <https://www.openssl.org/source/license.html>.

okay that's the whole page, you ate that 💜 — this cutie landed in OpenSSL 3.5.0, dated 2026-09-25, and that's the sign-off, mwah 🧚‍♀️✨

📦 where this page comes from