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

@@ -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,
@@ -389,6 +402,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

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,
@@ -487,6 +500,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