--- name: "libressl-PEM_read" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-PEM_read" --- # libressl-PEM\_read(3) PEM encoding routines ## NAME **PEM\_write**, **PEM\_write\_bio**, **PEM\_read**, **PEM\_read\_bio**, **PEM\_get\_EVP\_CIPHER\_INFO**, **PEM\_do\_header**, **PEM\_def\_callback**, **pem\_password\_cb** – PEM encoding routines ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *int*\ **PEM\_write**(*FILE \*fp*, *const char \*name*, *const char \*header*, *const unsigned char \*data*, *long len*); *int*\ **PEM\_write\_bio**(*BIO \*bp*, *const char \*name*, *const char \*header*, *const unsigned char \*data*, *long len*); *int*\ **PEM\_read**(*FILE \*fp*, *char \*\*name*, *char \*\*header*, *unsigned char \*\*data*, *long \*len*); *int*\ **PEM\_read\_bio**(*BIO \*bp*, *char \*\*name*, *char \*\*header*, *unsigned char \*\*data*, *long \*len*); *int*\ **PEM\_get\_EVP\_CIPHER\_INFO**(*char \*header*, *EVP\_CIPHER\_INFO \*cinfo*); *int*\ **PEM\_do\_header**(*EVP\_CIPHER\_INFO \*cinfo*, *unsigned char \*data*, *long \*len*, *pem\_password\_cb \*cb*, *void \*userdata*); *int*\ **PEM\_def\_callback**(*char \*password*, *int size*, *int verify*, *void \*userdata*); *typedef* *int*\ **pem\_password\_cb**(*char \*password*, *int size*, *int verify*, *void \*userdata*); ## DESCRIPTION These functions read and write PEM-encoded objects, using the PEM type *name*, any additional *header* information, and the raw *data* of length *len*. PEM is the binary content encoding first defined in IETF RFC 1421. The content is a series of base64-encoded lines, surrounded by begin/end markers each on their own line. For example: ``` -----BEGIN PRIVATE KEY----- MIICdg.... ... bhTQ== -----END PRIVATE KEY----- ``` Optional header line(s) may appear after the begin line, and their existence depends on the type of object being written or read. **PEM\_write**() writes to the file *fp*, while **PEM\_write\_bio**() writes to the BIO *bp*. The *name* is the name to use in the marker, the *header* is the header value or NULL, and *data* and *len* specify the data and its length. The final *data* buffer is typically an ASN.1 object which can be decoded with the **d2i\_\***() function appropriate to the type *name*; see d2i\_X509(3) for examples. **PEM\_read**() reads from the file *fp*, while **PEM\_read\_bio**() reads from the BIO *bp*. Both skip any non-PEM data that precedes the start of the next PEM object. When an object is successfully retrieved, the type name from the "----BEGIN \-----" is returned via the *name* argument, any encapsulation headers are returned in *header*, and the base64-decoded content and its length are returned via *data* and *len*, respectively. The *name*, *header*, and *data* pointers should be freed by the caller when no longer needed. The remaining functions are deprecated because the underlying PEM encryption format is obsolete and should be avoided. It uses an encryption format with an OpenSSL-specific key-derivation function, which employs MD5 with an iteration count of 1. Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5 v2.0 PBE; see PEM\_write\_PrivateKey(3) and d2i\_PKCS8PrivateKey\_bio(3). **PEM\_get\_EVP\_CIPHER\_INFO**() can be used to determine the *data* returned by **PEM\_read**() or **PEM\_read\_bio**() is encrypted and to retrieve the associated cipher and IV. The caller passes a pointer to a structure of type *EVP\_CIPHER\_INFO* via the *cinfo* argument and the *header* returned via **PEM\_read**() or **PEM\_read\_bio**(). If the call is successful, 1 is returned and the cipher and IV are stored at the address pointed to by *cinfo*. When the header is malformed or not supported or when the cipher is unknown or some internal error happens, 0 is returned. **PEM\_do\_header**() can then be used to decrypt the data if the header indicates encryption. The *cinfo* argument is a pointer to the structure initialized by a preceding call to **PEM\_get\_EVP\_CIPHER\_INFO**(). If that structure indicates the absence of encryption, **PEM\_do\_header**() returns successfully without taking any action. The *data* and *len* arguments are used both to pass in the encrypted data that was returned in the same arguments from the preceding call to **PEM\_read**() or **PEM\_read\_bio**() and to pass out the decrypted data. The callback function *cb* is used to obtain the encryption *password*; if *cb* is NULL, **PEM\_def\_callback**() is used instead. The *password* buffer needs to be at least *size* bytes long. Unless *userdata* is NULL, **PEM\_def\_callback**() ignores the *verify* argument and copies the NUL-terminated byte string *userdata* to *password* without a terminating NUL byte, silently truncating the copy to at most *size* bytes. If *userdata* is NULL, **PEM\_def\_callback**() instead prompts the user for the password with echoing turned off by calling EVP\_read\_pw\_string\_min(3) internally. In this case, the *size* is silently reduced to at most BUFSIZ and at most *size* - 1 bytes are accepted from the user and copied into the byte string buffer *password*. A callback function *cb* supplied by the application may use *userdata* for a different purpose than **PEM\_def\_callback**() does, e.g., as auxiliary data to use while acquiring the password. For example, a GUI application might pass a window handle. If the *verify* flag is non-zero, the user is prompted twice for the password to make typos less likely and it is checked that both inputs agree. This flag is not set by **PEM\_do\_header**() nor by other read functions, but it is typically set by write functions. If the data is a priori known to not be encrypted, then neither **PEM\_get\_EVP\_CIPHER\_INFO**() nor **PEM\_do\_header**() need to be called. ## RETURN VALUES **PEM\_read**() and **PEM\_read\_bio**() return 1 on success or 0 on failure. The latter includes the case when no more PEM objects remain in the input file. To distinguish end of file from more serious errors, the caller must peek at the error stack and check for PEM\_R\_NO\_START\_LINE, which indicates that no more PEM objects were found. See ERR\_peek\_last\_error(3) and ERR\_GET\_REASON(3). **PEM\_get\_EVP\_CIPHER\_INFO**() and **PEM\_do\_header**() return 1 on success or 0 on failure. The *data* is likely meaningless if these functions fail. **PEM\_def\_callback**() returns the number of bytes stored into *buf* or a negative value on failure, and *cb* is expected to behave in the same way. If *userdata* is NULL, **PEM\_def\_callback**() fails if *num* is less than 5 or if an error occurs trying to prompt the user for the password. Otherwise, it fails when *num* is negative. The details of the circumstances that cause *cb* to fail may differ. ## SEE ALSO [crypto(3)](/crypto/3.md), d2i\_PKCS8PrivateKey\_bio(3), PEM\_ASN1\_read(3), PEM\_bytes\_read\_bio(3), PEM\_read\_bio\_PrivateKey(3), PEM\_read\_SSL\_SESSION(3), PEM\_write\_bio\_CMS\_stream(3), PEM\_write\_bio\_PKCS7\_stream(3), PEM\_X509\_INFO\_read\_bio(3) ## HISTORY **PEM\_write**(), **PEM\_read**(), and **PEM\_do\_header**() appeared in SSLeay 0.4 or earlier. **PEM\_get\_EVP\_CIPHER\_INFO**() first appeared in SSLeay 0.5.1. **PEM\_write\_bio**() and **PEM\_read\_bio**() first appeared in SSLeay 0.6.0. These functions have been available since OpenBSD 2.4. **PEM\_def\_callback**() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2.