document PEM_ASN1_read(3) and PEM_ASN1_read_bio(3);

tweaks and OK tb@

1 files changed, 50 insertions, 2 deletions

diff --git a/src/lib/libcrypto/man/PEM_bytes_read_bio.3 b/src/lib/libcrypto/man/PEM_bytes_read_bio.3
index b3cb143cf6..63b8a58d90 100644
--- a/src/lib/libcrypto/man/PEM_bytes_read_bio.3
+++ b/src/lib/libcrypto/man/PEM_bytes_read_bio.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: PEM_bytes_read_bio.3,v 1.2 2018/03/22 21:08:22 schwarze Exp $
+.\"     $OpenBSD: PEM_bytes_read_bio.3,v 1.3 2020/06/12 11:37:42 schwarze Exp $
 .\"     OpenSSL PEM_bytes_read_bio.pod 7671342e Feb 29 15:47:12 2016 -0600
 .\"
 .\" This file was written by Benjamin Kaduk <bkaduk at akamai dot com>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 22 2018 $
+.Dd $Mdocdate: June 12 2020 $
 .Dt PEM_BYTES_READ_BIO 3
 .Os
 .Sh NAME
@@ -86,6 +86,8 @@ The password callback
 and rock
 .Fa u
 are used to obtain the decryption passphrase, if applicable.
+For more details, see
+.Xr pem_password_cb 3 .
 .Pp
 Some data types have compatibility aliases, such as a file containing
 X509 CERTIFICATE matching a request for the deprecated type CERTIFICATE.
@@ -107,7 +109,53 @@ The caller must free the storage pointed to by
 .Sh RETURN VALUES
 .Fn PEM_bytes_read_bio
 returns 1 for success or 0 for failure.
+.Sh ERRORS
+Diagnostics that can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3
+include:
+.Bl -tag -width Ds
+.It Dv PEM_R_NO_START_LINE Qq 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
+.Fa name .
+.It Dv PEM_R_NOT_PROC_TYPE Qq not proc type
+The first PEM header does not start with
+.Qq "Proc-Type: " .
+.It Dv PEM_R_NOT_ENCRYPTED Qq not encrypted
+The Proc-Type header differs from
+.Qq 4,ENCRYPTED .
+.It Dv PEM_R_SHORT_HEADER Qq short header
+The Proc-Type header is the last header line.
+.It Dv PEM_R_NOT_DEK_INFO Qq not dek info
+The second PEM header does not start with
+.Qq "DEK-Info: " .
+.It Dv PEM_R_UNSUPPORTED_ENCRYPTION Qq unsupported encryption
+The cipher name given in the DEK-Info header is unknown to
+.Xr EVP_get_cipherbyname 3 .
+.It Dv PEM_R_BAD_IV_CHARS Qq "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.
+.It Dv PEM_R_BAD_PASSWORD_READ Qq bad password read
+.Fa cb
+reported failure.
+This may for example happen when the user mistypes the password.
+.It Dv PEM_R_BAD_DECRYPT Qq bad decrypt
+.Xr EVP_DecryptInit_ex 3 ,
+.Xr EVP_DecryptUpdate 3 ,
+or
+.Xr EVP_DecryptFinal_ex 3
+failed.
+.El
+.Pp
+Additional types of errors can result from
+.Xr PEM_read_bio 3 .
 .Sh SEE ALSO
+.Xr PEM_ASN1_read 3 ,
 .Xr PEM_read 3 ,
 .Xr PEM_read_bio_PrivateKey 3
 .Sh HISTORY