[glib/mcatanzaro/validation-flags: 17/18] gtlsclientconnection: deprecate validation-flags property

[Philip Withnall <pwithnall src gnome org>]

commit 38de97c14804f41597a2be1f662f74c951040d90
Author: Michael Catanzaro <mcatanzaro redhat com>
Date:   Wed Aug 4 15:20:03 2021 -0500

    gtlsclientconnection: deprecate validation-flags property
    
    It doesn't work as expected, and you shouldn't be trying to use it
    anyway.

 gio/gtlsclientconnection.c | 29 ++++++++++++++++++++++++++++-
 gio/gtlsclientconnection.h |  4 ++--
 2 files changed, 30 insertions(+), 3 deletions(-)
---
diff --git a/gio/gtlsclientconnection.c b/gio/gtlsclientconnection.c
index d0a740f4f..63dd6bee7 100644
--- a/gio/gtlsclientconnection.c
+++ b/gio/gtlsclientconnection.c
@@ -59,7 +59,21 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
    * ways indicated here will be rejected unless the application
    * overrides the default via #GTlsConnection::accept-certificate.
    *
+   * GLib guarantees that if certificate verification fails, at least one
+   * flag will be set, but it does not guarantee that all possible flags
+   * will be set. Accordingly, you may not safely decide to ignore any
+   * particular type of error. For example, it would be incorrect to mask
+   * %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates,
+   * because this could potentially be the only error flag set even if
+   * other problems exist with the certificate. Therefore, there is no
+   * safe way to use this property. This is not a horrible problem,
+   * though, because you should not be attempting to ignore validation
+   * errors anyway. If you really must ignore TLS certificate errors,
+   * connect to #GTlsConnection::accept-certificate.
+   *
    * Since: 2.28
+   *
+   * Deprecated: 2.72: Do not attempt to ignore validation errors.
    */
   g_object_interface_install_property (iface,
                                       g_param_spec_flags ("validation-flags",
@@ -69,7 +83,8 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
                                                           G_TLS_CERTIFICATE_VALIDATE_ALL,
                                                           G_PARAM_READWRITE |
                                                           G_PARAM_CONSTRUCT |
-                                                          G_PARAM_STATIC_STRINGS));
+                                                          G_PARAM_STATIC_STRINGS |
+                                                          G_PARAM_DEPRECATED));
 
   /**
    * GTlsClientConnection:server-identity:
@@ -183,9 +198,15 @@ g_tls_client_connection_new (GIOStream           *base_io_stream,
  *
  * Gets @conn's validation flags
  *
+ * This function does not work as originally designed and is impossible
+ * to use correctly. See #GTlsClientConnection:validation-flags for more
+ * information.
+ *
  * Returns: the validation flags
  *
  * Since: 2.28
+ *
+ * Deprecated: 2.72: Do not attempt to ignore validation errors.
  */
 GTlsCertificateFlags
 g_tls_client_connection_get_validation_flags (GTlsClientConnection *conn)
@@ -207,7 +228,13 @@ g_tls_client_connection_get_validation_flags (GTlsClientConnection *conn)
  * checks performed when validating a server certificate. By default,
  * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
  *
+ * This function does not work as originally designed and is impossible
+ * to use correctly. See #GTlsClientConnection:validation-flags for more
+ * information.
+ *
  * Since: 2.28
+ *
+ * Deprecated: 2.72: Do not attempt to ignore validation errors.
  */
 void
 g_tls_client_connection_set_validation_flags (GTlsClientConnection  *conn,
diff --git a/gio/gtlsclientconnection.h b/gio/gtlsclientconnection.h
index 29dbafcf4..f592fa808 100644
--- a/gio/gtlsclientconnection.h
+++ b/gio/gtlsclientconnection.h
@@ -59,9 +59,9 @@ GIOStream *           g_tls_client_connection_new                  (GIOStream
                                                                    GSocketConnectable      *server_identity,
                                                                    GError                 **error);
 
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_72
 GTlsCertificateFlags  g_tls_client_connection_get_validation_flags (GTlsClientConnection    *conn);
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_72
 void                  g_tls_client_connection_set_validation_flags (GTlsClientConnection    *conn,
                                                                    GTlsCertificateFlags     flags);
 GLIB_AVAILABLE_IN_ALL