PKCS12_SAFEBAG_NEW(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 PKCS12_SAFEBAG_NEW — bestie edition

okay so this is page 3 of the libcrypto manual, and today we're learning about PKCS12_SAFEBAG_NEW(3). it's giving ✨ crypto container realness ✨ and honestly? she's iconic.

✨ NAME ✨

PKCS12_SAFEBAG_new, PKCS12_SAFEBAG_free, PKCS12_BAGS_new, PKCS12_BAGS_free — the PKCS#12 container for one piece of information 🎀

like, one (1) single little item. a lil guy. a bag inside a bag. iykyk.

🦋 SYNOPSIS 🦋

so first you gotta grab the library, she lives in libcrypto:

library “libcrypto” #include <openssl/pkcs12.h>

and here's the whole friend group — four functions, all matching, all slaying:

PKCS12_SAFEBAG *
PKCS12_SAFEBAG_new(void);

void
PKCS12_SAFEBAG_free(PKCS12_SAFEBAG *safebag);

PKCS12_BAGS *
PKCS12_BAGS_new(void);

void
PKCS12_BAGS_free(PKCS12_BAGS *bag);

notice how the _new girlies take void and return a pointer, and the _free girlies take a pointer and return void? that's balance. that's harmony. that's the vibe check passing 🔥

🌸 DESCRIPTION 🌸

💖 PKCS12_SAFEBAG_new() 💖

she allocates and initializes an empty PKCS12_SAFEBAG object, which represents an ASN.1 SafeBag structure — as defined in RFC 7292 section 4.2, no cap.

what can she hold? so glad you asked:

  • a pointer to a PKCS12_BAGS object
  • together with a type identifier
  • and optional attributes

she's basically a labeled little tote bag for your data. main character energy tbh 🫶

💜 PKCS12_SAFEBAG_free() 💜

frees safebag. that's it. that's the whole function. she cleans up after the party 🧹

🎀 PKCS12_BAGS_new() 🎀

allocates and initializes an empty PKCS12_BAGS object — and this one represents the bagValue field of an ASN.1 SafeBag structure. so like, the actual contents of the bag. the filling, if you will 🍓

she's used inside PKCS12_SAFEBAG and she can hold any of these:

  • a DER-encoded X.509 certificate
  • a base64-encoded SDSI certificate
  • a DER-encoded X.509 CRL
  • or other user-defined information

versatile queen 👑

💅 PKCS12_BAGS_free() 💅

frees bag. also it. also the whole function. 💀

⚠️ the plot twist ⚠️

okay bestie listen up, this part is lowkey important:

if an instance of PKCS12_SAFEBAG contains PKCS8_PRIV_KEY_INFO, X509_SIG, or nested PKCS12_SAFEBAG objects, the respective pointers are stored directly in the PKCS12_SAFEBAG object rather than in the contained PKCS12_BAGS object as required by RFC 7292.

yes, you read that right. it deviates from the spec. not me defending it, just reporting the facts fr fr 🙈

🌈 RETURN VALUES 🌈

  • PKCS12_SAFEBAG_new() and PKCS12_BAGS_new() return the new PKCS12_SAFEBAG or PKCS12_BAGS object, respectively — cute, correct, exactly what you wanted 💖
  • or NULL if an error occurs. so like... always check. please check. i'm begging 🥺

👑 SEE ALSO 👑

the whole extended universe, go read these next:

that's seven links. we love a well-connected friend group ✨

⭐ STANDARDS ⭐

  • RFC 7292: PKCS #12: Personal Information Exchange Syntax, section 4.2: The SafeBag Type

go read it, it's giving documentation but make it lore 📖

🕰️ HISTORY 🕰️

PKCS12_SAFEBAG_new(), PKCS12_SAFEBAG_free(), PKCS12_BAGS_new(), and PKCS12_BAGS_free() first appeared in OpenSSL 0.9.3 and have been available since OpenBSD 2.6.

vintage. retro. still relevant. we stan a long-lived API 🫶

and that's the page bestie! no cap, you now understand PKCS#12 safe bags better than most people. periodt 💅✨

anyway this came from the Debian build, dated June 8, 2025, and it's the PKCS12_SAFEBAG_NEW(3) page — mwah, love u, go write some correct crypto code 🌸🦋💜

📦 where this page comes from