SSL_SET1_INITIAL_PEER_ADDR(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 SSL_set1_initial_peer_addr — the OpenSSL 3SSL manual, but make it make sense 💖

okay bestie, so this page lives in the OpenSSL 3SSL manual section, and it's literally all about telling a QUIC connection where the server actually is before you even say hi. it's giving "let me set the vibe before the first message". 🦋

✨ NAME ✨

SSL_set1_initial_peer_addr — set the initial peer address for a QUIC connection

like, the very first address a QUIC client tries to reach. no cap. 👑

🌸 SYNOPSIS 🌸

#include <openssl/ssl.h>

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

that's it, that's the whole door. two things go in: your SSL object s and a BIO_ADDR pointer addr, and out comes an int. 💅

💫 DESCRIPTION 💫

okay so real talk. SSL_set1_initial_peer_addr() sets the initial destination peer address — the address your QUIC client-side connection is gonna aim at when it first tries to establish itself. main character energy for the handshake. 🔥

but hold up, there are rules, bestie:

  • this function can be used only on a QUIC connection SSL object. not just any random SSL *. she has a type, and the type is QUIC.
  • it can be used only before a connection attempt is first made. once you've started connecting, doors closed, no takebacks, periodt.
  • addr must point to a BIO_ADDR that represents a UDP destination address of the server you wanna connect to. literally the address of the server. not optional. 🫶

🎀 the automatic detection thing (yes, it's kinda iconic) 🎀

so here's the tea. if you hand a QUIC connection object a write BIO that supports the BIO_CTRL_DGRAM_GET_PEER control (for example, BIO_s_dgram), the initial destination peer address can be detected automatically. she's self-sufficient, she's independent. ✨

the deets:

  • if BIO_CTRL_DGRAM_GET_PEER returns a valid (non-AF_UNSPEC) peer address
  • and no valid peer address has yet been set

…then that address gets set automatically as the initial peer address. cute, right? 🌈

and because we love options here, you can override this behaviour by calling SSL_set1_initial_peer_addr() with a valid peer address explicitly. you're the boss, girlboss. 💅

🦋 important lil disclaimer, don't skip this part 🦋

the destination address used by QUIC may change over time in response to connection events, such as connection migration (where supported). so like... things move. people change. addresses change. 😭

SSL_set1_initial_peer_addr() configures the destination address used for initial connection establishment — and that's it. it does not confer any guarantee about the destination address being used for communication at any later time in the connection lifecycle. fr fr, read that one again. no promises about the future, only about the first step. 💀

💜 memory ownership moment 💜

this function makes a copy of the address passed by the caller. so the BIO_ADDR structure pointed to by addr may be freed by the caller after this function returns. you handed over a copy, she doesn't need your original anymore. free it, bestie, it's fine. 🎀

⭐ RETURN VALUES ⭐

  • returns 1 on success 🎉
  • returns 0 on failure 💀

that's the whole vibe check. one good, zero bad.

🌟 SEE ALSO 🌟

go read those next, iykyk. 📚

🧚 HISTORY 🧚

the SSL_set1_initial_peer_addr() function was added in OpenSSL 3.2. so if you're on something older, she hasn't been born yet. 🙈

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>.

aaaaand that's the page, bestie!! 🫶 this was OpenSSL version 4.0.3, dated 2026-09-29, living its best life under the SSL_SET1_INITIAL_PEER_ADDR(3SSL) name. go forth and set those initial peer addresses, you absolute icon. slay. 💖✨🌸

📦 where this page comes from