BIO_F_BASE64(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 BIO_F_BASE64 💖

okay bestie, gather round, because we're talking about BIO_f_base64 from the OpenSSL 3SSL manual — it's literally the base64 glow-up filter and it's iconic.

🌸 NAME 🌸

BIO_f_base64 — the base64 BIO filter, no cap 💅

✨ SYNOPSIS ✨

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

const BIO_METHOD *BIO_f_base64(void);

🦋 DESCRIPTION 🦋

so BIO_f_base64() hands you back the base64 BIO method. it's a filter BIO, which means it base64-encodes literally everything you write through it, and decodes everything you read through it. she's giving translator energy 🌈

Base64 BIOs do NOT support BIO_gets() or BIO_puts(). like, not a thing. don't even try it 🙈

when you're writing ✍️ — by default the output gets chopped into lines that are 64 characters long, and there's a newline at the end of the output. you can change that whole situation with the BIO_FLAGS_BASE64_NO_NL flag.

when you're reading 👀 — the first line of base64 content should be at most 1024 bytes long, newline included, unless the BIO_FLAGS_BASE64_NO_NL flag is set. after that, subsequent input lines can be literally any length (meaning newlines can pop up anywhere in the input, she doesn't care) and you don't need a newline at the end of the input. periodt.

also while reading, unless BIO_FLAGS_BASE64_NO_NL is set, any initial lines that have non-base64 content get skipped (whitespace is tolerated and ignored, she's chill like that), and so do lines longer than 1024 bytes. decoding starts with the first line that is shorter than 1024 bytes (newline included) and consists of only (at least one) valid base64 character plus optional whitespace. and decoding stops when:

  • base64 padding shows up, or
  • a soft end-of-input character — that's -, see EVP_DecodeUpdate(3) — happens as the first byte after a complete group of 4 valid base64 characters gets decoded, or
  • an error happens (like, say, input characters that aren't valid base64 or whitespace).

if decoding stops because of an error, the first BIO_read(3) that returns no decoded data will typically return a negative result instead of 0 (and 0 is what normally means "end of input, we're done here"). but heads up — a negative return value can also happen if the underlying BIO supports retries, so check BIO_should_read(3) and BIO_set_mem_eof_return(3).

BIO_flush() on a base64 BIO that's being written through is the signal that no more data is getting encoded: that's what flushes the final block through the BIO. 🚰

the BIO_FLAGS_BASE64_NO_NL flag can be set with BIO_set_flags(). for writing, it makes all the data get written on one single line with no newline at the end. for reading, it removes all expectations about newlines in the input data. she is unbothered. 💅

📝 NOTES 📝

because of how base64 encoding is formatted, the end of the encoded block can't always be reliably determined. it's giving mystery. 🕵️‍♀️

💫 RETURN VALUES 💫

BIO_f_base64() returns the base64 BIO method. that's it, that's the tea. ☕

🎀 EXAMPLES 🎀

base64 encode the string "Hello World\n" and write the result to standard output:

BIO *bio, *b64;
char message[] = "Hello World \n";

b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
BIO_write(b64, message, strlen(message));
BIO_flush(b64);

BIO_free_all(b64);

read base64 encoded data from standard input and write the decoded data to standard output:

BIO *bio, *b64, *bio_out;
char inbuf[512];
int inlen;

b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
while ((inlen = BIO_read(b64, inbuf, 512)) > 0)
    BIO_write(bio_out, inbuf, inlen);

BIO_flush(bio_out);
BIO_free_all(b64);

💀 BUGS 💀

the hyphen character (-) gets treated as an ad hoc soft end-of-input character when it shows up at the start of a base64 group of 4 encoded characters. lowkey unhinged but okay.

this heuristic works to detect the ends of base64 blocks in PEM or multi-part MIME — provided there are no stray hyphens in the middle of the input. but bestie, it is just a heuristic, and sufficiently unusual input could produce unexpected results. 🙈

there should perhaps be some way of specifying a test that the BIO can perform to reliably determine EOF (for example a MIME boundary). like, that would be the dream.

it may also be possible for BIO_read(3) to return zero rather than -1 even if an error has been detected — more tests are needed to cover all the potential error paths. 😭

🔥 SEE ALSO 🔥

Copyright 2000-2024 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.

and that's the whole page, bestie 🫶 this was OpenSSL 4.0.3, dated 2026-09-29, manual page BIO_F_BASE64(3SSL). slay, go forth and encode responsibly 💖✨🎀

📦 where this page comes from