[glib/mcatanzaro/gtlsdatabase-docs: 3/3] gtlsconnection: warn about footguns of using a non-default database

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 58b7f2e1ed1fccdd49cfe69040005fffa6d3c097
Author: Michael Catanzaro <mcatanzaro redhat com>
Date:   Tue Nov 9 17:15:28 2021 -0600

    gtlsconnection: warn about footguns of using a non-default database
    
    Since
    https://gitlab.gnome.org/GNOME/glib-networking/-/merge_requests/173,
    there is now a really surprising implication to using a non-default
    GTlsDatabase: your database could do nothing at all other than wrap the
    default database, which you would expect to result in no behavior
    changes, but in fact it causes fewer security checks to be performed
    during certificate verification. This is because certificate
    verification moved from GTlsDatabase to GTlsConnection, allowing for
    more security checks to be performed. But if using a non-default
    GTlsDatabase, we have to fall back to letting GTlsDatabase to the
    verification, as before.
    
    This is the best we can do. It's not a regression for applications,
    because it means applications get the previous pre-2.72 behavior. But it
    does mean that new security checks added in 2.72 are not applied, which
    is unfortunate, so we should warn developers about this.

 gio/gdtlsconnection.c | 16 ++++++++++++++++
 gio/gtlsconnection.c  | 16 ++++++++++++++++
 2 files changed, 32 insertions(+)
---
diff --git a/gio/gdtlsconnection.c b/gio/gdtlsconnection.c
index 880d87d2c..dde0df1c4 100644
--- a/gio/gdtlsconnection.c
+++ b/gio/gdtlsconnection.c
@@ -118,6 +118,19 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
    * If no certificate database is set, then the default database will be
    * used. See g_tls_backend_get_default_database().
    *
+   * When using a non-default database, #GDtlsConnection must fall back to using
+   * the #GTlsDatabase to perform certificate verification using
+   * g_tls_database_verify_chain(), which means certificate verification will
+   * not be able to make use of TLS session context. This may be less secure.
+   * For example, if you create your own #GTlsDatabase that just wraps the
+   * default #GTlsDatabase, you might expect that you have not changed anything,
+   * but this is not true because you may have altered the behavior of
+   * #GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the
+   * documentation of g_tls_database_verify_chain() for more details on specific
+   * security checks that may not be performed. Accordingly, setting a
+   * non-default database is discouraged except for specialty applications with
+   * unusual security requirements.
+   *
    * Since: 2.48
    */
   g_object_interface_install_property (iface,
@@ -372,6 +385,9 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
  * client-side connections, unless that bit is not set in
  * #GDtlsClientConnection:validation-flags).
  *
+ * There are nonintuitive security implications when using a non-default
+ * database. See #GDtlsConnection:database for details.
+ *
  * Since: 2.48
  */
 void
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index 0239489b7..894377c5e 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -143,6 +143,19 @@ g_tls_connection_class_init (GTlsConnectionClass *klass)
    * If no certificate database is set, then the default database will be
    * used. See g_tls_backend_get_default_database().
    *
+   * When using a non-default database, #GTlsConnection must fall back to using
+   * the #GTlsDatabase to perform certificate verification using
+   * g_tls_database_verify_chain(), which means certificate verification will
+   * not be able to make use of TLS session context. This may be less secure.
+   * For example, if you create your own #GTlsDatabase that just wraps the
+   * default #GTlsDatabase, you might expect that you have not changed anything,
+   * but this is not true because you may have altered the behavior of
+   * #GTlsConnection by causing it to use g_tls_database_verify_chain(). See the
+   * documentation of g_tls_database_verify_chain() for more details on specific
+   * security checks that may not be performed. Accordingly, setting a
+   * non-default database is discouraged except for specialty applications with
+   * unusual security requirements.
+   *
    * Since: 2.30
    */
   g_object_class_install_property (gobject_class, PROP_DATABASE,
@@ -470,6 +483,9 @@ g_tls_connection_get_use_system_certdb (GTlsConnection *conn)
  * client-side connections, unless that bit is not set in
  * #GTlsClientConnection:validation-flags).
  *
+ * There are nonintuitive security implications when using a non-default
+ * database. See #GDtlsConnection:database for details.
+ *
  * Since: 2.30
  */
 void