From 321ac1f2973c01f4a4a2719e4400c26ff01c3231 Mon Sep 17 00:00:00 2001
From: "Dr. David von Oheimb" <David.von.Oheimb@siemens.com>
Date: Sat, 20 Mar 2021 23:32:15 +0100
Subject: [PATCH] PEM_X509_INFO_read,{_bio}_ex(): Complete documentation in
 PEM_X509_INFO_read_bio_ex.pod

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14647)
---
 doc/man3/PEM_X509_INFO_read_bio_ex.pod | 30 +++++++++++++++++---------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/doc/man3/PEM_X509_INFO_read_bio_ex.pod b/doc/man3/PEM_X509_INFO_read_bio_ex.pod
index ceab8dbd687..f0add6537f9 100644
--- a/doc/man3/PEM_X509_INFO_read_bio_ex.pod
+++ b/doc/man3/PEM_X509_INFO_read_bio_ex.pod
@@ -3,8 +3,7 @@
 =head1 NAME
 
 PEM_X509_INFO_read_bio_ex, PEM_X509_INFO_read_ex
-- read a PEM-encoded data structure from a bio into one or more B<X509_INFO>
-object's
+- read PEM-encoded data structures into one or more B<X509_INFO> objects
 
 =head1 SYNOPSIS
 
@@ -23,17 +22,27 @@ object's
 
 =head1 DESCRIPTION
 
-The loaded B<X509_INFO> object's can contain a CRL, a certificate and a
-corresponding private key.
-
 PEM_X509_INFO_read_ex() loads the B<X509_INFO> objects from a file I<fp>.
-The library context I<libctx> and property query <propq> are used for fetching
-algorithms from providers.
 
-PEM_X509_INFO_read_bio_ex loads the B<X509_INFO> objects using a bio
-I<bp>. The library context I<libctx> and property query <propq> are used for
-fetching algorithms from providers.
+PEM_X509_INFO_read_bio_ex loads the B<X509_INFO> objects using a bio I<bp>.
+
+Each of the loaded B<X509_INFO> objects can contain a CRL, a certificate,
+and/or an RSA/DSA/EC private key.
+
+The elements are read sequentially, and as far as they are of different type than
+the elements read before, they are combined into the same B<X509_INFO> object.
+The idea behind this is that if, for instance, a certificate is followed by
+a private key, the private key is supposed to correspond to the certificate.
 
+If the input stack I<sk> is NULL a new stack is allocated,
+else the given stack is extended.
+
+The optional I<cb> and I<u> parameters can be used for providing a pass phrase
+needed for decrypting encrypted PEM structures (normally only private keys).
+See L<PEM_read_bio_PrivateKey(3)> and L<passphrase-encoding(7)> for details.
+
+The library context I<libctx> and property query <propq> are used for fetching
+algorithms from providers.
 
 =head1 RETURN VALUES
 
@@ -43,6 +52,7 @@ a stack of B<X509_INFO> objects or NULL on failure.
 =head1 SEE ALSO
 
 L<PEM_read_bio_ex(3)>,
+L<PEM_read_bio_PrivateKey(3)>,
 L<passphrase-encoding(7)>
 
 =head1 HISTORY
-- 
2.47.2