[glib/mcatanzaro/issuer-docs: 1/2] gtlsdatabase: improve documentation of lookup_certificate_issuer()

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 69fd1742e1e25bb3bc69d1d98a14dfb4de33ff3c
Author: Michael Catanzaro <mcatanzaro redhat com>
Date:   Wed Aug 4 09:35:16 2021 -0500

    gtlsdatabase: improve documentation of lookup_certificate_issuer()
    
    Because TLS certificate verification is extremely complex, this function
    may be tempting to misuse even by developers who are relatively familiar
    with TLS certificates. There is a notion that the issuer certificate
    will always be used in the final certification path, but it's just not
    always true. Trying to make security decisions based on the results of
    this function is a trap, so let's document that.

 gio/gtlsdatabase.c | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)
---
diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index d7dcf4bbe..5ab2b2f7f 100644
--- a/gio/gtlsdatabase.c
+++ b/gio/gtlsdatabase.c
@@ -783,14 +783,23 @@ g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase            *se
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: (nullable): a #GError, or %NULL
  *
- * Look up the issuer of @certificate in the database.
- *
- * The #GTlsCertificate:issuer property
- * of @certificate is not modified, and the two certificates are not hooked
- * into a chain.
- *
- * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
- * the lookup operation asynchronously.
+ * Look up the issuer of @certificate in the database. The
+ * #GTlsCertificate:issuer property of @certificate is not modified, and
+ * the two certificates are not hooked into a chain.
+ *
+ * Beware this function cannot be used to build certification paths. The
+ * issuer certificate returned by this function may not be the same as
+ * the certificate that would actually be used to construct a valid
+ * certification path during certificate verification.
+ * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+ * why an issuer certificate cannot be naively assumed to be part of the
+ * the certification path (though GLib's TLS backends may not follow the
+ * path building strategies outlined in this RFC). Due to the complexity
+ * of certification path building, GLib does not provide any way to know
+ * which certification path will actually be used.
+ *
+ * This function can block, use g_tls_database_lookup_certificate_issuer_async()
+ * to perform the lookup operation asynchronously.
  *
  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
  * or %NULL. Use g_object_unref() to release the certificate.