BIO_F_CIPHER(3SSL)

✨ BIO_F_CIPHER 💖 cipher BIO filter ✨

okay bestie, listen up, we're doing the OpenSSL manual pages and this one is genuinely a banger 💅. it's BIO_F_CIPHER(3SSL), and yes i know the name looks like someone fell asleep on their keyboard, but stay with me, this is the one that does encryption for you while you just vibe and write bytes. 🔥

---

🌸 NAME 🌸

BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx — it's the cipher BIO filter girlies. that's it, that's the whole name section, we're done here, moving on 🫶

---

🎀 SYNOPSIS 🎀

so this is what you actually type, copy it exactly bestie, no autocorrect please:

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

const BIO_METHOD *BIO_f_cipher(void);
int BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
                   const unsigned char *key, const unsigned char *iv, int enc);
int BIO_get_cipher_status(BIO *b);
int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx);

like, five whole things. slay. 👑

---

🌈 DESCRIPTION 🌈

okay so BIO_f_cipher() hands you back the cipher BIO method. and what even is that? it's a filter BIO, which means it sits there like the main character and encrypts literally any data you write through it, and decrypts literally any data you read from it. iconic behaviour, honestly. it's just a cute little BIO wrapper around the cipher routines EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal() — nothing more, nothing less, no cap. 💖

🚨 bestie PSA: cipher BIOs do not support BIO_gets() or BIO_puts(). like at all. don't try it.

BIO_flush() on an encryption BIO that you're actively writing through is ✨the signal✨ that no more data is to be encrypted — this is what flushes and possibly pads the final block through the BIO. it's giving "okay we're done here, wrap it up" 💅

BIO_set_cipher() sets the cipher of BIO b to cipher, using key key and IV iv. and enc? you set that to 1 for encryption and zero for decryption. one means encode, zero means decode, fr fr.

so when you're reading from an encryption BIO, the final block gets automatically decrypted and checked the moment EOF is detected, which is genuinely so thoughtful of it 🥹. and BIO_get_cipher_status() is a BIO_ctrl() macro you can call to find out whether that decryption operation actually succeeded or if it lowkey flopped.

and BIO_get_cipher_ctx()? also a BIO_ctrl() macro, and it retrieves the internal BIO cipher context. the retrieved context can be used alongside the standard cipher routines to set it up yourself. this is the move when BIO_set_cipher() just isn't flexible enough for what your application needs — like when you have ✨very specific✨ opinions. 💅

---

🦋 NOTES 🦋

• when encrypting, you must call BIO_flush() to flush the final block through the BIO. if you don't, the final block will fail a subsequent decrypt. not a vibe. not a slay. it will just break 💀
• when decrypting, an error on the final block is signalled by a zero return value from the read operation. but plot twist — a successful decrypt followed by EOF also returns zero for the final read 😭. so you genuinely cannot tell them apart just from the return value, and that's why you should call BIO_get_cipher_status() to determine if the decrypt was successful. periodt.
• as always, if you need BIO_gets() or BIO_puts() support, you can get it by preceding the cipher BIO with a buffering BIO. problem solved, bestie 🧚
• and here's the tea: BIO_f_cipher() uses a fixed size buffer when calling EVP_CipherUpdate(), which is a potential point of failure for ciphers that do not support streaming (such as AES-WRAP). so like, heads up. ⚠️

---

💜 RETURN VALUES 💜

• BIO_f_cipher() — returns the cipher BIO method. that's it, that's the whole thing, it's just handing you the method 🎀
• BIO_set_cipher() — returns 1 for success and 0 for failure.
• BIO_get_cipher_status() — returns 1 for a successful decrypt and <=0 for failure.
• BIO_get_cipher_ctx() — returns 1 for success and <=0 for failure.

---

👑 COPYRIGHT 👑

Copyright 2000-2026 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 and that's the whole page bestie, we ate and left no crumbs 🍓✨ this was version 4.0.3, dated 2026-09-29, and that's the BIO_F_CIPHER(3SSL) manual page, from your favourite OpenSSL. go encrypt something. responsibly. ily 🫶💖🌈