Merge branch 'mcatanzaro/gtlsdatabase-docs' into 'main'

Improve some documentation related to GTlsDatabase

See merge request GNOME/glib!2326

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/gtlscertificate.c

@@ -969,8 +969,8 @@ g_tls_certificate_get_issuer (GTlsCertificate  *cert)
  *
  * Because TLS session context is not used, #GTlsCertificate may not
  * perform as many checks on the certificates as #GTlsConnection would.
- * For example, certificate constraints cannot be honored, and some
- * revocation checks cannot be performed. The best way to verify TLS
+ * For example, certificate constraints may not be honored, and
+ * revocation checks may not be performed. The best way to verify TLS
  * certificates used by a TLS connection is to let #GTlsConnection
  * handle the verification.
  *

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

gio/gtlsdatabase.c

@@ -511,14 +511,14 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
  *
  * Because TLS session context is not used, #GTlsDatabase may not
  * perform as many checks on the certificates as #GTlsConnection would.
- * For example, certificate constraints cannot be honored, and some
- * revocation checks cannot be performed. The best way to verify TLS
+ * For example, certificate constraints may not be honored, and
+ * revocation checks may not be performed. The best way to verify TLS
  * certificates used by a TLS connection is to let #GTlsConnection
  * handle the verification.
  *
  * The TLS backend may attempt to look up and add missing certificates
- * to the chain. Since GLib 2.70, this may involve HTTP requests to
- * download missing certificates.
+ * to the chain. This may involve HTTP requests to download missing
+ * certificates.
  *
  * This function can block. Use g_tls_database_verify_chain_async() to
  * perform the verification operation asynchronously.