[openssl] master update

[Matt Caswell]

The branch master has been updated
       via  e48fe798409eb22f067f635c62b9a72e18cd4347 (commit)
      from  07f620e3acf0dd76a3a03ada9911c544aa483aa7 (commit)


- Log -----------------------------------------------------------------
commit e48fe798409eb22f067f635c62b9a72e18cd4347
Author: Matt Caswell <matt at openssl.org>
Date:   Thu Nov 11 12:09:15 2021 +0000

    Clarify the PEM docs
    
    Make it clear how the existing PEM functions can be used to create an
    X509, X509_REQ or X509_CRL object with an associated libctx/propq.
    
    Fixes #16966
    
    Reviewed-by: Tomas Mraz <tomas at openssl.org>
    Reviewed-by: Paul Dale <pauli at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/17012)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/PEM_read_bio_PrivateKey.pod | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 4ed1b8c703..2e4ab7e661 100644
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -209,7 +209,14 @@ refer to the B<PEM_read_bio_I<TYPE>>(), B<PEM_read_I<TYPE>>(),
 B<PEM_write_bio_I<TYPE>>(), and B<PEM_write_I<TYPE>>() functions.
 
 Some operations have additional variants that take a library context I<libctx>
-and a property query string I<propq>.
+and a property query string I<propq>. The B<X509>, B<X509_REQ> and B<X509_CRL>
+objects may have an associated library context or property query string but
+there are no variants of these functions that take a library context or property
+query string parameter. In this case it is possible to set the appropriate
+library context or property query string by creating an empty B<X509>,
+B<X509_REQ> or B<X509_CRL> object using L<X509_new_ex(3)>, L<X509_REQ_new_ex(3)>
+or L<X509_CRL_new_ex(3)> respectively. Then pass the empty object as a parameter
+to the relevant PEM function. See the L</EXAMPLES> section below.
 
 The B<PrivateKey> functions read or write a private key in PEM format using
 an EVP_PKEY structure. The write routines use PKCS#8 private key format and are
@@ -448,7 +455,8 @@ where I<x> already contains a valid certificate, may not work, whereas:
  X509_free(x);
  x = PEM_read_bio_X509(bp, NULL, 0, NULL);
 
-is guaranteed to work.
+is guaranteed to work. It is always acceptable for I<x> to contain a newly
+allocated, empty B<X509> object (for example allocated via L<X509_new_ex(3)>).
 
 =head1 RETURN VALUES