BIO_F_SSL(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 NAME 💅

Okay bestie, so this is the BIO_F_SSL(3ossl) manual page, and it's literally the whole SSL BIO saga, no cap. Buckle up 🎀

Here's the full cast of characters (and yes, they all live on this one page, iykyk):

  • BIO_do_handshake
  • BIO_f_ssl
  • BIO_set_ssl
  • BIO_get_ssl
  • BIO_set_ssl_mode
  • BIO_set_ssl_renegotiate_bytes
  • BIO_get_num_renegotiates
  • BIO_set_ssl_renegotiate_timeout
  • BIO_new_ssl
  • BIO_new_ssl_connect
  • BIO_new_buffer_ssl_connect
  • BIO_ssl_copy_session_id
  • BIO_ssl_shutdown

And the collective vibe? SSL BIO. That's it, that's the description. 💖

✨ SYNOPSIS ✨

Like, here's what you actually type:

#include <openssl/bio.h>
#include <openssl/ssl.h>

const BIO_METHOD *BIO_f_ssl(void);

long BIO_set_ssl(BIO *b, SSL *ssl, long c);
long BIO_get_ssl(BIO *b, SSL **sslp);
long BIO_set_ssl_mode(BIO *b, long client);
long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
long BIO_get_num_renegotiates(BIO *b);

BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
int BIO_ssl_copy_session_id(BIO *to, BIO *from);
void BIO_ssl_shutdown(BIO *bio);

long BIO_do_handshake(BIO *b);

Every single one of those, exactly as written. Copy-paste is self care 🫶

🌸 DESCRIPTION 🌸

The main character: BIO_f_ssl()

So BIO_f_ssl() hands you back the SSL BIO method. What even is that? It's a filter BIO — think of it as a cute little wrapper round the OpenSSL SSL routines that slaps an extra BIO "flavour" onto SSL I/O. It's giving ✨decorator pattern✨ but make it TLS.

When you do I/O on an SSL BIO, it talks using the SSL protocol with the SSL's read and write BIOs. And here's the tea: if an SSL connection isn't established yet, it just attempts to establish one on the first I/O call. No setup era required, it just goes 💅

If you append a BIO to an SSL BIO using BIO_push(), it's automatically used as the SSL BIO's read and write BIOs. Automatic. Iconic. No notes.

Resetting + freeing (the cleanup era 🧹)

Calling BIO_reset() on an SSL BIO closes down any current SSL connection by calling SSL_shutdown(). Then BIO_reset() gets sent to the next BIO in the chain — which will typically disconnect the underlying transport. After that, the SSL BIO is reset to the initial accept or connect state. So it's a full glow-up back to factory settings, basically.

And if the close flag is set when an SSL BIO is freed, then the internal SSL structure is also freed using SSL_free(). Important detail, don't sleep on it 🔥

All the setters and getters, one by one

  • BIO_set_ssl() — sets the internal SSL pointer of SSL BIO b to ssl, using the close flag c.
  • BIO_get_ssl() — retrieves the SSL pointer of SSL BIO b. Once you've got it, you can manipulate it with all the standard SSL library functions. Main character access unlocked 👑
  • BIO_set_ssl_mode() — sets the SSL BIO mode to client. If client is 1, client mode is set. If client is 0, server mode is set. Binary. Simple. We love a flag with commitment.
  • BIO_set_ssl_renegotiate_bytes() — sets the renegotiate byte count of SSL BIO b to num. Once set, after every num bytes of I/O (read and write), the SSL session is automatically renegotiated. Also: num must be at least 512 bytes. Not a suggestion, an actual requirement, fr fr.
  • BIO_set_ssl_renegotiate_timeout() — sets the renegotiate timeout of SSL BIO b to seconds. When the renegotiate timeout elapses, the session is automatically renegotiated. Clock's ticking bestie ⏰
  • BIO_get_num_renegotiates() — returns the total number of session renegotiations due to I/O or timeout of SSL BIO b. Your receipts, quantified 🧾

The constructor girlies 🎀

  • BIO_new_ssl() — allocates an SSL BIO using SSL_CTX ctx, and uses client mode if client is non zero.
  • BIO_new_ssl_connect() — creates a new BIO chain consisting of an SSL BIO (using ctx) followed by a connect BIO. Chain gang 🌈
  • BIO_new_buffer_ssl_connect() — creates a new BIO chain consisting of a buffering BIO, an SSL BIO (using ctx), and a connect BIO. Yes, three whole BIOs, she's stacked.

Chain surgery 🔧

  • BIO_ssl_copy_session_id() — copies an SSL session id between BIO chains from and to. How? By locating the SSL BIOs in each chain and calling SSL_copy_session_id() on the internal SSL pointer. Detective work, honestly.
  • BIO_ssl_shutdown() — closes down an SSL connection on BIO chain bio. It does this by locating the SSL BIO in the chain and calling SSL_shutdown() on its internal SSL pointer. Goodbye era 😭

BIO_do_handshake() — the moment of truth

BIO_do_handshake() attempts to complete an SSL handshake on the supplied BIO and establish the SSL connection. For non-SSL BIOs the connection is done typically at TCP level. And if domain name resolution yields multiple IP addresses, all of them are tried after connect() failures. She's persistent 💪

  • Returns 1 if the connection was established successfully.
  • Returns a zero or negative value if the connection could not be established.
  • For nonblocking connect BIOs, use BIO_should_retry() to figure out whether the call should be retried.
  • If a connection has already been established, this call has no effect. Nothing to see here, move along 🦋

🦋 NOTES 🦋

SSL BIOs are exceptional — and not just in the "she's so brave" way. If the underlying transport is non blocking, they can still request a retry in exceptional circumstances. Specifically, this happens if a session renegotiation takes place during a BIO_read_ex() operation — and one case where that happens is when step up occurs.

You can set the SSL flag SSL_AUTO_RETRY to disable this behaviour. Meaning: when this flag is set, an SSL BIO using a blocking transport will never request a retry. Boundaries! We love to see them 💅

Now, since unknown BIO_ctrl() operations are sent through filter BIOs, you can set the server's name and port using BIO_set_host() on the BIO returned by BIO_new_ssl_connect() without having to locate the connect BIO first. Convenience queen 👑

Applications do not have to call BIO_do_handshake() — but they may wish to do so, to separate the handshake process from other I/O processing. Optional, but sometimes you want the handshake to have its own solo moment ✨

Heads up: BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), BIO_get_num_renegotiates(), and BIO_do_handshake() are all implemented as macros. Surprise! They're not real functions, they're macros. Plot twist.
Also important, no cap: BIO_ssl_copy_session_id() is not currently supported on QUIC SSL objects and fails if called on such an object. So don't try it, bestie, she will not slay there 💀

⭐ RETURN VALUES ⭐

Here's the vibe check on what everything gives back:

  • BIO_f_ssl() returns the SSL BIO_METHOD structure. Simple, iconic, one job.
  • BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on success, or a value which is less than or equal to 0 if an error occurred. (Yes, less than or equal to zero. Read it again, it's not just negative 👀)
  • BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return a valid BIO structure on success, or NULL if an error occurred. Null check your constructors, besties, always.
  • BIO_ssl_copy_session_id() returns 1 on success, or 0 on error — or if called on a QUIC SSL object. (Remember the QUIC thing? Yeah. 0. That's the answer 🔥)
  • BIO_do_handshake() returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established.

okay so that's the whole setup — the functions, the flags, the return values, the warnings, all of it — but we are literally not even done yet, the examples are coming and they are LONG and they are GORGEOUS and you're gonna want to stick around for them 💜

okay so the legal bit, and honestly bestie it's short and slays:

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

That's the whole copyright line, fr — 2000-2023, The OpenSSL Project Authors, all rights reserved, no notes. 💅

Now the license tea: this file is licensed under the Apache License 2.0 (yep, that's the "License" with a capital L — capitalisation matters, iykyk). And this part is a real one, not a vibe suggestion: you may not use this file except in compliance with the License. Like, that's the actual condition of using it. 🙈

Want the full text? You can grab a copy in the file LICENSE in the source distribution, or online at:

https://www.openssl.org/source/license.html

That's it, that's the section — short, sweet, legally binding. 🎀

✨ and that's a wrap on BIO_F_SSL(3ossl), bestie ✨ this page is from OpenSSL 3.5.0, dated 2026-09-25 — go forth and filter your SSL BIOs responsibly, mwah 🫶💖

📦 where this page comes from