NAME
PEM_bytes_read_bio – read a PEM-encoded data structure from a BIO
SYNOPSIS
Crypto Library (libcrypto, -lcrypto)
#include <openssl/pem.h>
int
PEM_bytes_read_bio(unsigned char **pdata, long *plen, char **pnm, const char *name, BIO *in_bp, pem_password_cb *cb, void *u);
DESCRIPTION
PEM_bytes_read_bio() reads and PEM decodes the first object of type name (e.g. RSA PRIVATE KEY, CERTIFICATE, etc.) from in_bp. If multiple PEM-encoded data structures are present in the same stream, it skips non-matching data types and continues reading. Before reading each PEM object, lines not starting with "-----BEGIN " are also skipped; see PEM_read_bio(3) for details of PEM parsing.
The PEM header may indicate that the following data is encrypted; if so, the data is decrypted, optionally using cb and u, as described in pem_password_cb(3).
Some data types have compatibility aliases, such as a file containing X509 CERTIFICATE matching a request for the deprecated type CERTIFICATE. The actual type indicated by the file is returned in *pnm if pnm is non-NULL. The caller must free the storage pointed to by *pnm.
The returned data is the DER-encoded form of the requested type, in *pdata with length *plen. The caller must free the storage pointed to by *pdata.
RETURN VALUES
PEM_bytes_read_bio() returns 1 for success or 0 for failure.
ERRORS
Diagnostics that can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3) include:
- PEM_R_NO_START_LINE "no start line"
-
No more PEM objects were found in the input. This can happen when the input contains no PEM objects at all, or only objects that do not match the type name.
- PEM_R_NOT_PROC_TYPE "not proc type"
-
The first PEM header does not start with "Proc-Type: ".
- PEM_R_NOT_ENCRYPTED "not encrypted"
-
The Proc-Type header differs from "4,ENCRYPTED".
- PEM_R_SHORT_HEADER "short header"
-
The Proc-Type header is the last header line.
- PEM_R_NOT_DEK_INFO "not dek info"
-
The second PEM header does not start with "DEK-Info: ".
- PEM_R_UNSUPPORTED_ENCRYPTION "unsupported encryption"
-
The cipher name given in the DEK-Info header is unknown to EVP_get_cipherbyname(3).
- PEM_R_BAD_IV_CHARS "bad iv chars"
-
The word following the cipher name in the DEK-Info header contains bytes that are not hexadecimal digits. This also happens when the initialization vector is missing or too short.
- PEM_R_BAD_PASSWORD_READ "bad password read"
-
cb reported failure. This may for example happen when the user mistypes the password.
- PEM_R_BAD_DECRYPT "bad decrypt"
-
EVP_DecryptInit_ex(3), EVP_DecryptUpdate(3), or EVP_DecryptFinal_ex(3) failed.
Additional types of errors can result from PEM_read_bio(3).
SEE ALSO
PEM_ASN1_read(3), PEM_read(3), PEM_read_bio_PrivateKey(3), PEM_X509_INFO_read_bio(3)
STANDARDS
RFC 1421: Privacy Enhancement for Internet Electronic Mail (PEM), Part I
HISTORY
PEM_bytes_read_bio() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2.