BIO_NEW_CMS(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💅 BIO_new_CMS — the streaming filter BIO that's lowkey iconic 💅

okay so bestie, welcome to the OpenSSL corner of the manual pages, this one's from the 3ossl collection and it's literally all about BIO_new_CMS — the CMS streaming filter BIO. no cap, it's giving very niche but very useful energy. let's get into it 🫶

✨ SYNOPSIS ✨

like, here's the vibe check on how you actually call it:

#include <openssl/cms.h>

BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);

that's it. that's the whole signature. slay. 💅

🦋 DESCRIPTION 🦋

so BIO_new_CMS() returns a streaming filter BIO chain that's based on cms. the output of the filter gets written to out. any data you write to the chain is automatically translated to a BER format CMS structure of the appropriate type. it's giving "set it and forget it" but make it cryptography. ✨

🎀 NOTES 🎀

okay this is the part where you actually need to pay attention, bestie, because there's lore:

  • the chain returned by this function behaves like a standard filter BIO. it supports non blocking I/O. content is processed and streamed on the fly and not all held in memory at once — so it's possible to encode very large structures. main character energy fr fr. 🔥
  • after all content has been written through the chain, BIO_flush() must be called to finalise the structure. don't skip this, i'm begging. 😭
  • the CMS_STREAM flag must be included in the corresponding flags parameter of the cms creation function. it's not optional, it's a requirement, periodt. 👑
  • if an application wishes to write additional data to out, BIOs should be removed from the chain using BIO_pop() and freed with BIO_free() until out is reached. if no additional data needs to be written, BIO_free_all() can be called to free up the whole chain. choose your fighter. 🥊
  • any content written through the filter is used verbatim: no canonical translation is performed. what you write is what you get, no editing, no filter, no nothing. 🪞
  • it is possible to chain multiple BIOs to, for example, create a triple wrapped signed, enveloped, signed structure. in this case it is the application's responsibility to set the inner content type of any outer CMS_ContentInfo structures. you're the main character here, you gotta handle it. 💪
  • large numbers of small writes through the chain should be avoided as this will produce an output consisting of lots of OCTET STRING structures. prepending a BIO_f_buffer() buffering BIO will prevent this. like, don't spam tiny writes, it's not cute. buffer it. 🧚
ngl the CMS_STREAM flag thing and the BIO_flush() thing are the two places where people mess up, so like, don't be that person. 💀

💀 BUGS 💀

there is currently no corresponding inverse BIO: i.e. one which can decode a CMS structure on the fly. so like, you can encode but you can't decode in the same streaming way — that's just the situation, bestie. not me pointing it out but also yes me pointing it out. 🙈

🌈 RETURN VALUES 🌈

BIO_new_CMS() returns a BIO chain when successful or NULL if an error occurred. the error can be obtained from ERR_get_error(3). so if it comes back NULL, don't panic, just go check the error queue. iykyk. 🫶

🔥 SEE ALSO 🔥

go read those too, they're part of the whole ecosystem, it's a whole thing. 💖

⭐ HISTORY ⭐

the BIO_new_CMS() function was added in OpenSSL 1.0.0. so it's been around for a minute, it's not new new, it's vintage. icon behavior. 🎀

Copyright 2008-2016 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 so that's the whole page, bestie. this was OpenSSL 3.5.6, dated 2026-04-07, and it's the BIO_NEW_CMS(3ossl) manual page. go stream some CMS structures responsibly, and remember: BIO_flush() before you dip. 💖✨🎀🦋

mwah 💋

📦 where this page comes from