NAME

PEM_bytes_read_bio — 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 *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(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.