PEM_READ_BIO_PRIVATEKEY(3SSL)
💅 PEM_READ_BIO_PRIVATEKEY(3SSL) — PEM routines, but make it a group chat 💅
Okay so bestie, welcome to the OpenSSL manual page for PEM_READ_BIO_PRIVATEKEY(3SSL). The title is honestly a whole mouthful, but this page is the home base for a huge squad of PEM routines. Part 1 is just the NAME section, and it's giving "roll call at the function sleepover." No cap, every single one is about to get named. 💖
🎀 NAME 🎀
These are all the functions, symbols, and typedefs this page covers, and the official one-liner is simply PEM routines. Not me listing every single one because we do not skip anybody in this house. Here's the full lineup, exactly as listed:
pem_password_cbPEM_read_bio_PrivateKey_exPEM_read_bio_PrivateKeyPEM_read_PrivateKey_exPEM_read_PrivateKeyPEM_write_bio_PrivateKey_exPEM_write_bio_PrivateKeyPEM_write_bio_PrivateKey_traditionalPEM_write_PrivateKey_exPEM_write_PrivateKeyPEM_write_bio_PKCS8PrivateKeyPEM_write_PKCS8PrivateKeyPEM_write_bio_PKCS8PrivateKey_nidPEM_write_PKCS8PrivateKey_nidPEM_read_bio_PUBKEY_exPEM_read_bio_PUBKEYPEM_read_PUBKEY_exPEM_read_PUBKEYPEM_write_bio_PUBKEY_exPEM_write_bio_PUBKEYPEM_write_PUBKEY_exPEM_write_PUBKEYPEM_read_bio_RSAPrivateKeyPEM_read_RSAPrivateKeyPEM_write_bio_RSAPrivateKeyPEM_write_RSAPrivateKeyPEM_read_bio_RSAPublicKeyPEM_read_RSAPublicKeyPEM_write_bio_RSAPublicKeyPEM_write_RSAPublicKeyPEM_read_bio_RSA_PUBKEYPEM_read_RSA_PUBKEYPEM_write_bio_RSA_PUBKEYPEM_write_RSA_PUBKEYPEM_read_bio_DSAPrivateKeyPEM_read_DSAPrivateKeyPEM_write_bio_DSAPrivateKeyPEM_write_DSAPrivateKeyPEM_read_bio_DSA_PUBKEYPEM_read_DSA_PUBKEYPEM_write_bio_DSA_PUBKEYPEM_write_DSA_PUBKEYPEM_read_bio_Parameters_exPEM_read_bio_ParametersPEM_write_bio_ParametersPEM_read_bio_DSAparamsPEM_read_DSAparamsPEM_write_bio_DSAparamsPEM_write_DSAparamsPEM_read_bio_DHparamsPEM_read_DHparamsPEM_write_bio_DHparamsPEM_write_DHparamsPEM_read_bio_X509PEM_read_X509PEM_write_bio_X509PEM_write_X509PEM_read_bio_X509_ACERTPEM_read_X509_ACERTPEM_write_bio_X509_ACERTPEM_write_X509_ACERTPEM_read_bio_X509_AUXPEM_read_X509_AUXPEM_write_bio_X509_AUXPEM_write_X509_AUXPEM_read_bio_X509_REQPEM_read_X509_REQPEM_write_bio_X509_REQPEM_write_X509_REQPEM_write_bio_X509_REQ_NEWPEM_write_X509_REQ_NEWPEM_read_bio_X509_CRLPEM_read_X509_CRLPEM_write_bio_X509_CRLPEM_write_X509_CRLPEM_read_bio_PKCS7PEM_read_PKCS7PEM_write_bio_PKCS7PEM_write_PKCS7— PEM routines
More parts coming, so keep scrolling, bestie 💅✨
✨ SYNOPSIS ✨
okay bestie, deep breath 💖 this synopsis is long long. But don't panic — it's literally the same vibe over and over: PEM_read_* pulls something out of a file/BIO, PEM_write_* shoves it back in. Once you clock the pattern you're unstoppable. 👑
First, the headers and the password-callback squad:
#include <openssl/pem.h>
typedef int pem_password_cb(char *buf, int size, int rwflag, void *u);💜 Private keys (the main characters)
These are the ones the whole page is named after, so they get top billing:
EVP_PKEY *PEM_read_bio_PrivateKey_ex(BIO *bp, EVP_PKEY **x,
pem_password_cb *cb, void *u,
OSSL_LIB_CTX *libctx, const char *propq);
EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
EVP_PKEY *PEM_read_PrivateKey_ex(FILE *fp, EVP_PKEY **x, pem_password_cb *cb,
void *u, OSSL_LIB_CTX *libctx,
const char *propq);
EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_PrivateKey_ex(BIO *bp, const EVP_PKEY *x,
const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u,
OSSL_LIB_CTX *libctx, const char *propq);
int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_bio_PrivateKey_traditional(BIO *bp, const EVP_PKEY *x,
const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PrivateKey_ex(FILE *fp, const EVP_PKEY *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u,
OSSL_LIB_CTX *libctx, const char *propq);
int PEM_write_PrivateKey(FILE *fp, const EVP_PKEY *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);and the PKCS#8-flavoured writers, which take an int nid for the cipher instead of a whole EVP_CIPHER (the _nid ones, iykyk):
int PEM_write_bio_PKCS8PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PKCS8PrivateKey(FILE *fp, const EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, const EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);notice real quick: thePKCS8writers takechar *kstrwhile the private-key writers takeunsigned char *kstr. That's not a typo, that's just how they are. 🙈
🦋 Public keys
EVP_PKEY *PEM_read_bio_PUBKEY_ex(BIO *bp, EVP_PKEY **x,
pem_password_cb *cb, void *u,
OSSL_LIB_CTX *libctx, const char *propq);
EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
EVP_PKEY *PEM_read_PUBKEY_ex(FILE *fp, EVP_PKEY **x,
pem_password_cb *cb, void *u,
OSSL_LIB_CTX *libctx, const char *propq);
EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_PUBKEY_ex(BIO *bp, const EVP_PKEY *x,
OSSL_LIB_CTX *libctx, const char *propq);
int PEM_write_bio_PUBKEY(BIO *bp, const EVP_PKEY *x);
int PEM_write_PUBKEY_ex(FILE *fp, const EVP_PKEY *x,
OSSL_LIB_CTX *libctx, const char *propq);
int PEM_write_PUBKEY(FILE *fp, const EVP_PKEY *x);🌸 Parameters (no public option, just vibes)
EVP_PKEY *PEM_read_bio_Parameters_ex(BIO *bp, EVP_PKEY **x,
OSSL_LIB_CTX *libctx, const char *propq);
EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x);
int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x);no FILE * versions here bestie, BIO only. we respect the grind. 💅
🎀 X.509 certificates and friends
Plain certs first:
X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
int PEM_write_bio_X509(BIO *bp, const X509 *x);
int PEM_write_X509(FILE *fp, const X509 *x);Attribute certificates, which are a whole separate X509_ACERT type:
X509_ACERT *PEM_read_bio_X509_ACERT(BIO *bp, X509_ACERT **x,
pem_password_cb *cb, void *u);
X509_ACERT *PEM_read_X509_ACERT(FILE *fp, X509_ACERT **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_X509_ACERT(BIO *bp, const X509_ACERT *x);
int PEM_write_X509_ACERT(FILE *fp, const X509_ACERT *x);and the "trusted" ones with the _AUX suffix, which carry extra stuff alongside the cert:
X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
int PEM_write_bio_X509_AUX(BIO *bp, const X509 *x);
int PEM_write_X509_AUX(FILE *fp, const X509 *x);🌈 Certificate requests and CRLs
Requests — and note there are two write flavours, plain and _NEW:
X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
pem_password_cb *cb, void *u);
X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_X509_REQ(BIO *bp, const X509_REQ *x);
int PEM_write_X509_REQ(FILE *fp, const X509_REQ *x);
int PEM_write_bio_X509_REQ_NEW(BIO *bp, const X509_REQ *x);
int PEM_write_X509_REQ_NEW(FILE *fp, const X509_REQ *x);Certificate revocation lists, no _NEW drama, just the standard quartet:
X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
pem_password_cb *cb, void *u);
X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_X509_CRL(BIO *bp, const X509_CRL *x);
int PEM_write_X509_CRL(FILE *fp, const X509_CRL *x);🍓 PKCS7
PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
int PEM_write_bio_PKCS7(BIO *bp, const PKCS7 *x);
int PEM_write_PKCS7(FILE *fp, const PKCS7 *x);💀 The deprecated corner (OpenSSL 3.0 said bye)
okay so listen carefully bestie: these are deprecated since OpenSSL 3.0, and they can be hidden entirely by definingOPENSSL_API_COMPATwith a suitable version value — peepopenssl_user_macros(7). Not me warning you twice. 😭
RSA private keys
RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
pem_password_cb *cb, void *u);
RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_RSAPrivateKey(BIO *bp, const RSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_RSAPrivateKey(FILE *fp, const RSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);RSA public keys, old PEM style
RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
pem_password_cb *cb, void *u);
RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_RSAPublicKey(BIO *bp, const RSA *x);
int PEM_write_RSAPublicKey(FILE *fp, const RSA *x);RSA public keys, PUBKEY style
RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
pem_password_cb *cb, void *u);
RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_RSA_PUBKEY(BIO *bp, const RSA *x);
int PEM_write_RSA_PUBKEY(FILE *fp, const RSA *x);DSA, all of it
DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
pem_password_cb *cb, void *u);
DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_DSAPrivateKey(BIO *bp, const DSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_DSAPrivateKey(FILE *fp, const DSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
pem_password_cb *cb, void *u);
DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_DSA_PUBKEY(BIO *bp, const DSA *x);
int PEM_write_DSA_PUBKEY(FILE *fp, const DSA *x);
DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
int PEM_write_bio_DSAparams(BIO *bp, const DSA *x);
int PEM_write_DSAparams(FILE *fp, const DSA *x);DH parameters
DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
int PEM_write_bio_DHparams(BIO *bp, const DH *x);
int PEM_write_DHparams(FILE *fp, const DH *x);and that's the whole synopsis, every last prototype. phew. 🫶 the actual what-does-it-do tea is coming up next, don't go anywhere.
✨ DESCRIPTION ✨
Okay bestie, first things first, and I need you to hear me on this one: every single function on this page whose TYPE is DH, DSA or RSA? Deprecated. Like, "we still love her but she's retiring" deprecated. Applications should be using OSSL_ENCODER_to_bio(3) and OSSL_DECODER_from_bio(3) instead, periodt. 💅
So what are the PEM functions doing? They read or write structures in PEM format. And PEM format, at its core, is simply base64 encoded data surrounded by header lines. That's it. That's the whole vibe. 🎀
Want the deets on what all the arguments mean? Scroll down to the PEM FUNCTION ARGUMENTS section, iykyk.
So here's the structure, and it's giving very "four function girlies per operation" energy. Every operation has four functions hanging out together. For brevity (and because we're not typing all that out every time), the term "TYPE functions" below collectively refers to:
PEM_read_bio_TYPE()PEM_read_TYPE()PEM_write_bio_TYPE()PEM_write_TYPE()
Some operations also have additional variants that take a library context libctx and a property query string propq. Now here's the little plot twist 🌸: the X509, X509_REQ and X509_CRL objects can have an associated library context or property query string, BUT there are no variants of these functions that actually take a library context or property query string parameter. Awkward!
So what do you do? You set the appropriate library context or property query string by creating an empty X509, X509_REQ or X509_CRL object using X509_new_ex(3), X509_REQ_new_ex(3) or X509_CRL_new_ex(3) respectively. Then you pass that empty object as a parameter to the relevant PEM function. Slay, problem solved. 👑 See the EXAMPLES section below for the receipts.
The PrivateKey girlies 🔐
The PrivateKey functions read or write a private key in PEM format using an EVP_PKEY structure. The write routines use PKCS#8 private key format and are equivalent to PEM_write_bio_PKCS8PrivateKey(). The read functions transparently handle traditional and PKCS#8 format encrypted and unencrypted keys. Versatile queen. 💖
PEM_write_bio_PrivateKey_traditional() writes out a private key in the "traditional" format with a simple private key marker, and it should only be used for compatibility with legacy programs. It's giving grandfathered-in energy, ngl.
PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption algorithms. The cipher argument specifies the encryption algorithm to use. And here's a fun lil detail 🦋: unlike some other PEM routines, the encryption is applied at the PKCS#8 level and not in the PEM headers. If cipher is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo, however it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm to use is specified in the nid parameter and should be the NID of the corresponding OBJECT IDENTIFIER (see the NOTES section, bestie).
The PUBKEY girlies 🔑
The PUBKEY functions process a public key using an EVP_PKEY structure. The public key is encoded as a SubjectPublicKeyInfo structure. Iconic, standard, we stan. ✨
The RSA girlies 🌈
- The RSAPrivateKey functions process an RSA private key using an
RSAstructure. The write routines use traditional format. The read routines handle the same formats as the PrivateKey functions but an error occurs if the private key is not RSA. Rude if it's not RSA, honestly. - The RSAPublicKey functions process an RSA public key using an
RSAstructure. The public key is encoded using a PKCS#1 RSAPublicKey structure. - The RSA_PUBKEY functions also process an RSA public key using an
RSAstructure. However, the public key is encoded using a SubjectPublicKeyInfo structure and an error occurs if the public key is not RSA. Same energy, different encoding. 💅
The DSA girlies 🦋
- The DSAPrivateKey functions process a DSA private key using a
DSAstructure. The write routines use traditional format. The read routines handle the same formats as the PrivateKey functions but an error occurs if the private key is not DSA. - The DSA_PUBKEY functions process a DSA public key using a
DSAstructure. The public key is encoded using a SubjectPublicKeyInfo structure and an error occurs if the public key is not DSA.
The Parameters girlies 🎀
The Parameters functions read or write key parameters in PEM format using an EVP_PKEY structure. The encoding depends on the type of key:
- for DSA key parameters, it will be a Dss-Parms structure as defined in RFC 3370
- for DH key parameters, it will be a PKCS#3 DHparameter structure
Oh and heads up — these functions only exist for the BIO type. No FILE pointer variant, sorry bestie. 🙈
The DSAparams and DHparams girlies 🌸
- The DSAparams functions process DSA parameters using a
DSAstructure. The parameters are encoded using a Dss-Parms structure as defined in RFC 3370. - The DHparams functions process DH parameters using a
DHstructure. The parameters are encoded using a PKCS#3 DHparameter structure.
The X509 girlies 👑
The X509 functions process an X509 certificate using an X509 structure. They will also process a trusted X509 certificate but any trust settings are discarded. Rip to those trust settings, they were lowkey not invited. 💀
The X509_ACERT functions process an X509 attribute certificate using an X509_ACERT structure.
The X509_AUX functions process a trusted X509 certificate using an X509 structure.
The X509_REQ girlies 📜
The X509_REQ and X509_REQ_NEW functions process a PKCS#10 certificate request using an X509_REQ structure. Here's the tea ☕: the X509_REQ write functions use CERTIFICATE REQUEST in the header whereas the X509_REQ_NEW functions use NEW CERTIFICATE REQUEST (as required by some CAs). The X509_REQ read functions will handle either form so there are no X509_REQ_NEW read functions. No need, the readers are already eating. 🔥
The X509_CRL and PKCS7 girlies 🌟
The X509_CRL functions process an X509 CRL using an X509_CRL structure.
The PKCS7 functions process a PKCS#7 ContentInfo using a PKCS7 structure.
🫶 PEM FUNCTION ARGUMENTS 🫶
Okay so the PEM functions have a lot of arguments in common, so let's break it down bestie.
The BIO and FILE params 💖
- The
bpBIO parameter (if present) specifies the BIO to read from or write to. ThebpBIO parameter MUST NOT be NULL. Like, do not. Please. 🙏 - The
fpFILE parameter (if present) specifies the FILE pointer to read from or write to.
The read params ✨
The PEM read functions all take an argument TYPE **x and return a TYPE * pointer. Where TYPE is whatever structure the function uses. Here's how it goes:
- If
xisNULLthen the parameter is ignored. - If
xis notNULLbut*xisNULLthen the structure returned will be written to*x. - If neither
xnor*xisNULLthen an attempt is made to reuse the structure at*x(but see the BUGS and EXAMPLES sections 👀).
Irrespective of the value of x, a pointer to the structure is always returned (or NULL if an error occurred). The caller retains ownership of the returned object and needs to free it when it is no longer needed, e.g. using X509_free() for X509 objects or EVP_PKEY_free() for EVP_PKEY objects. Don't forget to free her, she's your responsibility now. 💜
The encryption param and the passphrase saga 🔑
The PEM functions which write private keys take an enc parameter which specifies the encryption algorithm to use. Encryption is done at the PEM level. If this parameter is set to NULL then the private key is written in unencrypted form. (Spicy. 🌶️)
The cb argument is the callback to use when querying for the pass phrase used for encrypted PEM structures (normally only private keys).
For the PEM write routines, if the kstr parameter is not NULL then klen bytes at kstr are used as the passphrase and cb is ignored.
If the cb parameter is set to NULL and the u parameter is not NULL then the u parameter is interpreted as a NUL terminated string to use as the passphrase. If both cb and u are NULL then the default callback routine is used, which will typically prompt for the passphrase on the current terminal with echoing turned off. ✨ (Echoing off = nobody peeking at your secrets, we love that for you.)
The custom callback option 🎀
The default passphrase callback is sometimes inappropriate (for example in a GUI application) so an alternative can be supplied. The callback routine has the following form:
int cb(char *buf, int size, int rwflag, void *u);Breaking it down, because every detail matters:
bufis the buffer to write the passphrase to.sizeis the maximum length of the passphrase (i.e. the size ofbuf).rwflagis a flag which is set to0when reading and1when writing. A typical routine will ask the user to verify the passphrase (for example by prompting for it twice) ifrwflagis1.- The
uparameter has the same value as theuparameter passed to the PEM routine. It allows arbitrary data to be passed to the callback by the application (for example a window handle in a GUI application).
The callback must return the number of characters in the passphrase or -1 if an error occurred. And this is important, bestie: the passphrase can be arbitrary data; in the case where it is a string, it is not NUL terminated. See the EXAMPLES section below. 🌸
The libctx and propq deets 🦋
Some implementations may need to use cryptographic algorithms during their operation. If this is the case and libctx and propq parameters have been passed then any algorithm fetches will use that library context and property query string. Otherwise the default library context and property query string will be used. Simple as that. 💅
📝 NOTES 📝
The PEM reading functions will skip any extraneous content or PEM data of a different type than they expect. This allows for example having a certificate (or multiple certificates) and a key in the PEM format in a single file. One file, many vibes. 🔥
The old PrivateKey write routines are retained for compatibility. New applications should write private keys using the PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines because they are more secure (they use an iteration count of 2048 whereas the traditional routines use a count of 1) unless compatibility with older versions of OpenSSL is important. Number check: 2048 vs 1. That's not a competition, that's a massacre. 💀
The PrivateKey read routines can be used in all applications because they handle all formats transparently. Flexible queen. 👑
A frequent cause of problems is attempting to use the PEM routines like this:
X509 *x;
PEM_read_bio_X509(bp, &x, 0, NULL);this is a bug because an attempt will be made to reuse the data at x which is an uninitialised pointer. Do not do this. I am begging. 😭
These functions make no assumption regarding the pass phrase received from the password callback. It will simply be treated as a byte sequence. Byte sequence. That's it. No opinions. 🫶
🔐 PEM ENCRYPTION FORMAT 🔐
okay bestie, sit DOWN — these old PrivateKey routines use a non standard technique for encryption. it's giving ✨legacy✨ but we're gonna learn it anyway 💖
The private key (or other data) takes the following form:
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
...base64 encoded data...
-----END RSA PRIVATE KEY-----The line beginning with Proc-Type contains the version and the protection on the encapsulated data. The line beginning DEK-Info contains two comma separated values: the encryption algorithm name as used by EVP_get_cipherbyname() and an initialization vector used by the cipher encoded as a set of hexadecimal digits. After those two lines is the base64-encoded encrypted data. slay, that's the whole layout 💅
The encryption key is derived using EVP_BytesToKey(). The cipher's initialization vector is passed to EVP_BytesToKey() as the salt parameter. Internally, PKCS5_SALT_LEN bytes of the salt are used (regardless of the size of the initialization vector). The user's password is passed to EVP_BytesToKey() using the data and datal parameters. Finally, the library uses an iteration count of 1 for EVP_BytesToKey(). yes bestie, a count of ONE, that's literally the whole security budget 🙈
The key derived by EVP_BytesToKey() along with the original initialization vector is then used to decrypt the encrypted data. The iv produced by EVP_BytesToKey() is not utilized or needed, and NULL should be passed to the function. throwing it away, iconic behaviour honestly 🎀
The pseudo code to derive the key would look similar to:
EVP_CIPHER* cipher = EVP_des_ede3_cbc();
EVP_MD* md = EVP_md5();
unsigned int nkey = EVP_CIPHER_get_key_length(cipher);
unsigned int niv = EVP_CIPHER_get_iv_length(cipher);
unsigned char key[nkey];
unsigned char iv[niv];
memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv);
rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/);
if (rc != nkey)
/* Error */
/* On success, use key and iv to initialize the cipher */💀 BUGS 💀
ngl this part is a lil cursed, so read it twice bestie 😭
The PEM read routines in some versions of OpenSSL will not correctly reuse an existing structure. Therefore, the following:
PEM_read_bio_X509(bp, &x, 0, NULL);where x already contains a valid certificate, may not work, whereas:
X509_free(x);
x = PEM_read_bio_X509(bp, NULL, 0, NULL);is guaranteed to work. It is always acceptable for x to contain a newly allocated, empty X509 object (for example allocated via X509_new_ex(3)). so like, free it first, bestie, it's not that deep 🌸
🫶 RETURN VALUES 🫶
The read routines return either a pointer to the structure read or NULL if an error occurred. no half-measures, it's either the goods or nothing ✨
The write routines return 1 for success or 0 for failure. binary queen behaviour 👑
🌈 EXAMPLES 🌈
Although the PEM routines take several arguments in almost all applications most of them are set to 0 or NULL. we love a low-effort call signature 💅
To read a certificate with a library context in PEM format from a BIO:
X509 *x = X509_new_ex(libctx, NULL);
if (x == NULL)
/* Error */
if (PEM_read_bio_X509(bp, &x, 0, NULL) == NULL)
/* Error */Read a certificate in PEM format from a BIO:
X509 *x;
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
if (x == NULL)
/* Error */Alternative method:
X509 *x = NULL;
if (!PEM_read_bio_X509(bp, &x, 0, NULL))
/* Error */Write a certificate to a BIO:
if (!PEM_write_bio_X509(bp, x))
/* Error */Write a private key (using traditional format) to a BIO using triple DES encryption, the pass phrase is prompted for:
if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
/* Error */Write a private key (using PKCS#8 format) to a BIO using triple DES encryption, using the pass phrase "hello":
if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
NULL, 0, 0, "hello"))
/* Error */Read a private key from a BIO using a pass phrase callback:
key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
if (key == NULL)
/* Error */Skeleton pass phrase callback:
int pass_cb(char *buf, int size, int rwflag, void *u)
{
/* We'd probably do something else if 'rwflag' is 1 */
printf("Enter pass phrase for \"%s\"\n", (char *)u);
/* get pass phrase, length 'len' into 'tmp' */
char *tmp = "hello";
if (tmp == NULL) /* An error occurred */
return -1;
size_t len = strlen(tmp);
if (len > size)
len = size;
memcpy(buf, tmp, len);
return len;
}👀 SEE ALSO 👀
📜 HISTORY 📜
The old Netscape certificate sequences were no longer documented in OpenSSL 1.1.0; applications should use the PKCS7 standard instead as they will be formally deprecated in a future releases. rip to the old ones, they lived 🕊️
PEM_read_bio_PrivateKey_ex(), PEM_read_PrivateKey_ex(), PEM_read_bio_PUBKEY_ex(), PEM_read_PUBKEY_ex() and PEM_read_bio_Parameters_ex() were introduced in OpenSSL 3.0.
The functions PEM_read_bio_RSAPrivateKey(), PEM_read_RSAPrivateKey(), PEM_write_bio_RSAPrivateKey(), PEM_write_RSAPrivateKey(), PEM_read_bio_RSAPublicKey(), PEM_read_RSAPublicKey(), PEM_write_bio_RSAPublicKey(), PEM_write_RSAPublicKey(), PEM_read_bio_RSA_PUBKEY(), PEM_read_RSA_PUBKEY(), PEM_write_bio_RSA_PUBKEY(), PEM_write_RSA_PUBKEY(), PEM_read_bio_DSAPrivateKey(), PEM_read_DSAPrivateKey(), PEM_write_bio_DSAPrivateKey(), PEM_write_DSAPrivateKey(), PEM_read_bio_DSA_PUBKEY(), PEM_read_DSA_PUBKEY(), PEM_write_bio_DSA_PUBKEY(), PEM_write_DSA_PUBKEY(); PEM_read_bio_DSAparams(), PEM_read_DSAparams(), PEM_write_bio_DSAparams(), PEM_write_DSAparams(), PEM_read_bio_DHparams(), PEM_read_DHparams(), PEM_write_bio_DHparams() and PEM_write_DHparams() were deprecated in 3.0. they're on the way out bestie, don't get attached 😭
PEM_read_bio_X509_ACERT(), PEM_read_X509_ACERT(), PEM_write_bio_X509_ACERT(), PEM_write_X509_ACERT() were added in OpenSSL 3.4.
💜 COPYRIGHT 💜
Copyright 2001-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.
aaaand that's the whole manual, start to finish, bestie 🎀 you just read the entire PEM_READ_BIO_PRIVATEKEY(3SSL) page and I'm so proud, no cap fr fr 🥹 This one's from OpenSSL 4.0.3, dated 2026-09-29 — screenshot it, cite it, text it to the group chat, whatever 💅✨ bye ily 🦋🌸
📦 where this page comes from
- ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms