[openssl] OpenSSL_1_1_1-stable update

[Richard Levitte]

The branch OpenSSL_1_1_1-stable has been updated
       via  5a070488d8c7b31da9080e6fcce6aefdc86af608 (commit)
      from  9f084451a33d60c3da6833739f6e26f203ca85d2 (commit)


- Log -----------------------------------------------------------------
commit 5a070488d8c7b31da9080e6fcce6aefdc86af608
Author: Richard Levitte <levitte at openssl.org>
Date:   Mon Apr 15 17:30:11 2019 +0200

    doc/man3/X509_LOOKUP_meth_new.pod: clarify the requirements
    
    The documentation of what a X509_LOOKUP implementation must do was
    unclear and confusing.  Most of all, clarification was needed that it
    must store away the found objects in the X509_STORE.
    
    Fixes #8707
    
    Reviewed-by: Paul Dale <paul.dale at oracle.com>
    (Merged from https://github.com/openssl/openssl/pull/8755)
    
    (cherry picked from commit 19f43f02aa5349034d0a7a60c3a750e046f994b5)

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

Summary of changes:
 doc/man3/X509_LOOKUP_meth_new.pod | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/doc/man3/X509_LOOKUP_meth_new.pod b/doc/man3/X509_LOOKUP_meth_new.pod
index fb165fd..430124c 100644
--- a/doc/man3/X509_LOOKUP_meth_new.pod
+++ b/doc/man3/X509_LOOKUP_meth_new.pod
@@ -150,10 +150,20 @@ the X509_LOOKUP context, the type of the X509_OBJECT being requested, parameters
 related to the lookup, and an X509_OBJECT that will receive the requested
 object.
 
-Implementations should use either X509_OBJECT_set1_X509() or
-X509_OBJECT_set1_X509_CRL() to set the result. Any method data that was
-created as a result of the new_item function set by
-X509_LOOKUP_meth_set_new_item() can be accessed with
+Implementations must add objects they find to the B<X509_STORE> object
+using X509_STORE_add_cert() or X509_STORE_add_crl().  This increments
+its reference count.  However, the X509_STORE_CTX_get_by_subject()
+function also increases the reference count which leads to one too
+many references being held.  Therefore applications should
+additionally call X509_free() or X509_CRL_free() to decrement the
+reference count again.
+
+Implementations should also use either X509_OBJECT_set1_X509() or
+X509_OBJECT_set1_X509_CRL() to set the result.  Note that this also
+increments the result's reference count.
+
+Any method data that was created as a result of the new_item function
+set by X509_LOOKUP_meth_set_new_item() can be accessed with
 X509_LOOKUP_get_method_data(). The B<X509_STORE> object that owns the
 X509_LOOKUP may be accessed with X509_LOOKUP_get_store(). Successful lookups
 should return 1, and unsuccessful lookups should return 0.