PEM_BYTES_READ_BIO(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 PEM_BYTES_READ_BIO(3SSL) — the OpenSSL manual, but make it make sense 💖

okay bestie, pull up a chair, we're reading PEM data out of a BIO and honestly? it's giving ✨iconic✨. this is page PEM_BYTES_READ_BIO(3SSL) from the OpenSSL fam, and we're about to get into it.

🌸 NAME 🌸

PEM_bytes_read_bio, PEM_bytes_read_bio_secmem — read a PEM-encoded data structure from a BIO 🎀

✨ SYNOPSIS ✨

#include <openssl/pem.h>

int PEM_bytes_read_bio(unsigned char **pdata, long *plen, char **pnm,
                       const char *name, BIO *bp, pem_password_cb *cb,
                       void *u);
int PEM_bytes_read_bio_secmem(unsigned char **pdata, long *plen, char **pnm,
                              const char *name, BIO *bp, pem_password_cb *cb,
                              void *u);

🦋 DESCRIPTION 🦋

so PEM_bytes_read_bio() reads PEM-formatted data — that's IETF RFC 1421 and IETF RFC 7468, for the record, not me making that up — from the BIO bp, and it's looking for the data type you named in name (think RSA PRIVATE KEY, CERTIFICATE, etc.). lowkey versatile.

here's the cute part: if there are multiple PEM-encoded data structures chillin' in the same stream, PEM_bytes_read_bio() will just skip right past the ones that don't match your data type and keep reading. main character energy honestly. 🙈 but heads up — non-PEM data sitting in the stream may cause an error. so like, don't do that.

the PEM header can also tell you that the data coming up is encrypted, and if so, it gets decrypted, and it'll wait on user input to get a passphrase if it needs one. the password callback cb and the rock u are what you use to grab that decryption passphrase, if applicable. 🫶

some data types have compatibility aliases — classic — like a file containing X509 CERTIFICATE matching a request for the deprecated type CERTIFICATE. the actual type the file says it is gets returned in *pnm, but only if pnm is non-NULL. bestie, the caller must free the storage that *pnm points to. no leaks, we don't do that here. 💅

the data you get back is the DER-encoded form of the type you asked for, sitting in *pdata with length *plen. and yep — the caller must free the storage pointed to by *pdata too. freeing your stuff is self care, periodt.

PEM_bytes_read_bio_secmem() is basically PEM_bytes_read_bio()'s more careful sibling ✨ — it uses memory from the secure heap for its temporary buffers and for the storage returned in *pdata and *pnm. which means, accordingly, the caller has to use OPENSSL_secure_free() to free that storage. different free function, don't mix them up, iykyk.

📝 NOTES 📝

okay this part is important so listen up. PEM_bytes_read_bio_secmem() only enforces that the secure heap is used for storage allocated within the PEM processing stack. the BIO stack that you're reading input from may also use temporary buffers, and those are not necessarily allocated from the secure heap. 💀

so if you're in a situation where you really need to make sure the contents of the PEM file only ever appear in memory from the secure heap, you gotta be careful when generating the BIO you pass as bp. specifically: using BIO_s_file() means you're using the operating system stdio functionality, which includes buffering as a feature — and that's not what you want here. BIO_s_fd() is likely to be more appropriate in those cases. 🧚

also, these functions make no assumption about the pass phrase they receive from the password callback. it's just treated as a byte sequence. that's it, that's the whole vibe. no encoding judgment whatsoever.

🌈 RETURN VALUES 🌈

PEM_bytes_read_bio() and PEM_bytes_read_bio_secmem() return 1 for success or 0 for failure. that's the whole scale, no in-between, no "it depends". 🎀

👀 SEE ALSO 👀

⭐ HISTORY ⭐

PEM_bytes_read_bio_secmem() was introduced in OpenSSL 1.1.1 — so she's not ancient, she's just well-established. 👑

Copyright 2017-2018 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>.

fr fr, that's the whole page. go free your *pdata and your *pnm, bestie, and if you used the secmem one, use OPENSSL_secure_free() — I'm not gonna say it again (I will say it again). 💜

and that's a wrap on this one, gorgeous — this page came from OpenSSL 4.0.3, dated 2026-09-29, and it's filed under PEM_BYTES_READ_BIO(3SSL). slay 🫶✨

📦 where this page comes from