BIO_F_SSL(3SSL)

📦

version 4.0.3 · 14 versions

💅 BIO_F_SSL — the SSL BIO, bestie edition ✨

okay so this is the manual page for BIO_F_SSL(3SSL) in OpenSSL, and it's a LOT, so buckle up 🫶

✨ NAME ✨

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 — the SSL BIO 💖

🌸 SYNOPSIS 🌸

#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);

🦋 DESCRIPTION 🦋

BIO_f_ssl() hands you back the SSL BIO method. It's a filter BIO — basically it's a little wrapper round the OpenSSL SSL routines that slaps a BIO "flavour" onto SSL I/O ✨

When you do I/O on an SSL BIO, it talks using the SSL protocol with the SSL's read and write BIOs. And if there's no SSL connection set up yet? It just tries to establish one on the very first I/O call. no drama 💅

If you append a BIO to an SSL BIO with BIO_push(), it automatically becomes the SSL BIO's read and write BIOs. convenient much? 👑

Calling BIO_reset() on an SSL BIO closes down any current SSL connection by calling SSL_shutdown(). Then BIO_reset() gets sent on to the next BIO in the chain — which will typically disconnect the underlying transport. After that the SSL BIO gets reset back to its initial accept or connect state 🔄

If the close flag is set when an SSL BIO is freed, then the internal SSL structure also gets freed with SSL_free().

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, and once you have it you can go wild with the standard SSL library functions 💖
BIO_set_ssl_mode() — sets the SSL BIO mode to client. If client is 1, client mode is on. If client is 0, server mode is on.
BIO_set_ssl_renegotiate_bytes() — sets the renegotiate byte count of SSL BIO b to num. Once it's set, after every num bytes of I/O (both read and write 😌) the SSL session gets automatically renegotiated. and num must be at least 512 bytes, no negotiation on that one.
BIO_set_ssl_renegotiate_timeout() — sets the renegotiate timeout of SSL BIO b to seconds. When that timeout elapses, the session automatically renegotiates ⏰
BIO_get_num_renegotiates() — returns the total number of session renegotiations (due to I/O or timeout) of SSL BIO b.
BIO_new_ssl() — allocates an SSL BIO using SSL_CTX ctx, in client mode if client is non zero.
BIO_new_ssl_connect() — creates a whole new BIO chain: an SSL BIO (using ctx) followed by a connect BIO 🚂
BIO_new_buffer_ssl_connect() — creates a whole new BIO chain too: a buffering BIO, then an SSL BIO (using ctx), then a connect BIO 🚂🚃
BIO_ssl_copy_session_id() — copies an SSL session id between the BIO chains from and to, by locating the SSL BIOs in each chain and calling SSL_copy_session_id() on the internal SSL pointer.
BIO_ssl_shutdown() — closes down an SSL connection on BIO chain bio, by locating the SSL BIO in the chain and calling SSL_shutdown() on its internal SSL pointer.
BIO_do_handshake() — tries to complete an SSL handshake on the BIO you hand it, and establish the SSL connection. For non-SSL BIOs, the connection is done typically at TCP level. If domain name resolution gives you multiple IP addresses, all of them are tried after connect() failures 👀 It returns 1 if the connection was established successfully. A zero or negative value means the connection could not be established. For nonblocking connect BIOs you should use BIO_should_retry() to figure out if the call should be retried. And if a connection has already been established, this call just... does nothing. no effect. periodt 💅

💜 NOTES 💜

SSL BIOs are exceptional — like, 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 — one case where that happens is when step up occurs 👀

The SSL flag SSL_AUTO_RETRY can be set to disable this behaviour. That is, when this flag is set, an SSL BIO using a blocking transport will never request a retry.

Since unknown BIO_ctrl() operations get 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 go locate the connect BIO first 🎀 iykyk.

Applications don't have to call BIO_do_handshake(), but they might wanna, so they can separate the handshake process from other I/O processing.

heads up bestie: 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 implemented as macros.

Also! BIO_ssl_copy_session_id() is not currently supported on QUIC SSL objects and it fails if you call it on one of those.

⭐ RETURN VALUES ⭐

BIO_f_ssl() returns the SSL BIO_METHOD structure.
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 less than or equal to 0 if an error happened 😭
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 happened.
BIO_ssl_copy_session_id() returns 1 on success or 0 on error — or 0 if it was called on a QUIC SSL object.
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.

🍓 EXAMPLES 🍓

This SSL/TLS client example tries to retrieve a page from an SSL/TLS web server. The I/O routines are identical to those of the unencrypted example in BIO_s_connect(3) ✨

        BIO *sbio, *out;
        int len;
        char tmpbuf[1024];
        SSL_CTX *ctx;
        SSL *ssl;

        /* XXX Seed the PRNG if needed. */

        ctx = SSL_CTX_new(TLS_client_method());

        /* XXX Set verify paths and mode here. */

        sbio = BIO_new_ssl_connect(ctx);
        BIO_get_ssl(sbio, &ssl);
        if (ssl == NULL) {
            fprintf(stderr, "Can't locate SSL pointer\n");
            ERR_print_errors_fp(stderr);
            exit(1);
        }

        /* XXX We might want to do other things with ssl here */

        /* An empty host part means the loopback address */
        BIO_set_conn_hostname(sbio, ":https");

        out = BIO_new_fp(stdout, BIO_NOCLOSE);
        if (BIO_do_connect(sbio) <= 0) {
            fprintf(stderr, "Error connecting to server\n");
            ERR_print_errors_fp(stderr);
            exit(1);
        }

        /* XXX Could examine ssl here to get connection info */

        BIO_puts(sbio, "GET / HTTP/1.0\n\n");
        for (;;) {
            len = BIO_read(sbio, tmpbuf, 1024);
            if (len <= 0)
                break;
            BIO_write(out, tmpbuf, len);
        }
        BIO_free_all(sbio);
        BIO_free(out);

And here's a simple server example 💖 It makes use of a buffering BIO so lines can be read from the SSL BIO using BIO_gets. It creates a pseudo web page containing the actual request from a client, and also echoes the request to standard output 🎀

        BIO *sbio, *bbio, *acpt, *out;
        int len;
        char tmpbuf[1024];
        SSL_CTX *ctx;
        SSL *ssl;

        /* XXX Seed the PRNG if needed. */

        ctx = SSL_CTX_new(TLS_server_method());
        if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
                || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
                || !SSL_CTX_check_private_key(ctx)) {
            fprintf(stderr, "Error setting up SSL_CTX\n");
            ERR_print_errors_fp(stderr);
            exit(1);
        }

        /* XXX Other things like set verify locations, EDH temp callbacks. */

        /* New SSL BIO setup as server */
        sbio = BIO_new_ssl(ctx, 0);
        BIO_get_ssl(sbio, &ssl);
        if (ssl == NULL) {
            fprintf(stderr, "Can't locate SSL pointer\n");
            ERR_print_errors_fp(stderr);
            exit(1);
        }

        bbio = BIO_new(BIO_f_buffer());
        sbio = BIO_push(bbio, sbio);
        acpt = BIO_new_accept("4433");

        /*
         * By doing this when a new connection is established
         * we automatically have sbio inserted into it. The
         * BIO chain is now 'swallowed' by the accept BIO and
         * will be freed when the accept BIO is freed.
         */
        BIO_set_accept_bios(acpt, sbio);
        out = BIO_new_fp(stdout, BIO_NOCLOSE);

        /* First call to BIO_do_accept() sets up accept BIO */
        if (BIO_do_accept(acpt) <= 0) {
            fprintf(stderr, "Error setting up accept BIO\n");
            ERR_print_errors_fp(stderr);
            exit(1);
        }

       /* Second call to BIO_do_accept() waits for incoming connection */
        if (BIO_do_accept(acpt) <= 0) {
           fprintf(stderr, "Error accepting connection\n");
           ERR_print_errors_fp(stderr);
           exit(1);
        }

        /* We only want one connection so remove and free accept BIO */
        sbio = BIO_pop(acpt);
        BIO_free_all(acpt);

        if (BIO_do_handshake(sbio) <= 0) {
            fprintf(stderr, "Error in SSL handshake\n");
            ERR_print_errors_fp(stderr);
            exit(1);
        }

        BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
        BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
        BIO_puts(sbio, "--------------------------------------------------\r\n");

        for (;;) {
            len = BIO_gets(sbio, tmpbuf, 1024);
            if (len <= 0)
                break;
            BIO_write(sbio, tmpbuf, len);
            BIO_write(out, tmpbuf, len);
            /* Look for blank line signifying end of headers*/
            if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
                break;
        }

        BIO_puts(sbio, "--------------------------------------------------\r\n");
        BIO_puts(sbio, "\r\n");
        BIO_flush(sbio);
        BIO_free_all(sbio);

📜 HISTORY 📜

okay so tea time ☕ In OpenSSL before 1.0.0, the BIO_pop() call was handled incorrectly — the I/O BIO reference count was incorrectly incremented (instead of decremented) and dissociated with the SSL BIO even if the SSL BIO was not explicitly being popped (e.g. a pop higher up the chain) 💀

Applications that included workarounds for this bug (e.g. freeing BIOs more than once) should be modified to handle this fix, or they may free up an already freed BIO. not it. 🙈

📜 COPYRIGHT (aka the legal bestie section, pls read it 🫶)

Okay so before anyone comes for me — this whole page, all of it, is:

And it's licensed under the Apache License 2.0 — yep, "the License", capital L and all. You're only allowed to use this file if you actually follow the License, no vibes-based lawyering, no cap. 🚫⚖️

Wanna peep the full License text yourself? It's living right there in the file LICENSE in the source distribution, or you can go grab a copy here:

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

That's it, that's the legalese, she's giving "short but legally binding" and honestly? iconic. 💅

and that's a wrap on BIO_F_SSL(3SSL) bestie!! ✨ this one came straight from the OpenSSL 4.0.3 distribution, dated 2026-09-29 — go forth, wrap your BIOs in SSL, and slay responsibly 🦋💖🌸

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms