[glib/mcatanzaro/issuer-docs: 2/2] gtlscertificate: improve documentation of issuer property

[Michael Catanzaro <mcatanzaro src gnome org>]

commit e100278d905e6d61cbd3b801e2e8158149cde2a2
Author: Michael Catanzaro <mcatanzaro redhat com>
Date:   Wed Aug 4 09:45:32 2021 -0500

    gtlscertificate: improve documentation of issuer property

 gio/gtlscertificate.c | 11 +++++++++++
 1 file changed, 11 insertions(+)
---
diff --git a/gio/gtlscertificate.c b/gio/gtlscertificate.c
index 308a0a7ed..20635cb88 100644
--- a/gio/gtlscertificate.c
+++ b/gio/gtlscertificate.c
@@ -226,6 +226,17 @@ g_tls_certificate_class_init (GTlsCertificateClass *class)
    * self-signed, or else the certificate of the issuer is not
    * available.
    *
+   * Beware the issuer certificate may not be the same as the
+   * certificate that would actually be used to construct a valid
+   * certification path during certificate verification. Accordingly,
+   * this property cannot be used to make security-related decisions.
+   * [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.
+   *
    * Since: 2.28
    */
   g_object_class_install_property (gobject_class, PROP_ISSUER,