[glib/mcatanzaro/tls1.3-handshake] Deprecate TLS rehandshake APIs

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 0766aa7c8b61ea8dbae4cafe26121b4fe498aa1a
Author: Michael Catanzaro <mcatanzaro igalia com>
Date:   Sat Nov 17 11:30:02 2018 -0600

    Deprecate TLS rehandshake APIs
    
    Allowing unsafe rehandshakes used to be required for web compatibility,
    but this is no longer a concern in 2018. So there should no longer be
    compatibility benefits to calling this function. All it does is make
    your TLS connection insecure.
    
    Also, rehandshaking no longer exists at all in TLS 1.3.
    
    At some point (maybe soon!) glib-networking will begin ignoring the
    rehandshake mode, so let's deprecate it now.

 gio/gdtlsconnection.c | 19 +++++++++++++++++--
 gio/gdtlsconnection.h |  4 ++--
 gio/gioenums.h        |  4 ++++
 gio/gtlsconnection.c  | 11 ++++++++++-
 gio/gtlsconnection.h  |  4 ++--
 5 files changed, 35 insertions(+), 7 deletions(-)
---
diff --git a/gio/gdtlsconnection.c b/gio/gdtlsconnection.c
index cbcb720dc..541500392 100644
--- a/gio/gdtlsconnection.c
+++ b/gio/gdtlsconnection.c
@@ -162,6 +162,10 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
    * g_dtls_connection_set_rehandshake_mode().
    *
    * Since: 2.48
+   *
+   * Deprecated: 2.60. Changing the rehandshake mode is no longer
+   *   required for compatibility. Also, rehandshaking has been removed
+   *   from the TLS protocol in TLS 1.3.
    */
   g_object_interface_install_property (iface,
                                        g_param_spec_enum ("rehandshake-mode",
@@ -597,6 +601,10 @@ g_dtls_connection_get_require_close_notify (GDtlsConnection *conn)
  * software.
  *
  * Since: 2.48
+ *
+ * Deprecated: 2.60. Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 void
 g_dtls_connection_set_rehandshake_mode (GDtlsConnection     *conn,
@@ -656,8 +664,15 @@ g_dtls_connection_get_rehandshake_mode (GDtlsConnection       *conn)
  * Likewise, on the server side, although a handshake is necessary at
  * the beginning of the communication, you do not need to call this
  * function explicitly unless you want clearer error reporting.
- * However, you may call g_dtls_connection_handshake() later on to
- * renegotiate parameters (encryption methods, etc) with the client.
+ *
+ * If TLS 1.2 or older is in use, you may call
+ * g_dtls_connection_handshake() after the initial handshake to
+ * rehandshake; however, this usage is deprecated because rehandshaking
+ * is no longer part of the TLS protocol in TLS 1.3. Accordingly, the
+ * behavior of calling this function after the initial handshake is now
+ * undefined, except it is guaranteed to be reasonable and
+ * nondestructive so as to preserve compatibility with code written for
+ * older versions of GLib.
  *
  * #GDtlsConnection::accept_certificate may be emitted during the
  * handshake.
diff --git a/gio/gdtlsconnection.h b/gio/gdtlsconnection.h
index 207b6dfde..3cf6cb31c 100644
--- a/gio/gdtlsconnection.h
+++ b/gio/gdtlsconnection.h
@@ -123,10 +123,10 @@ void                  g_dtls_connection_set_require_close_notify    (GDtlsConnec
 GLIB_AVAILABLE_IN_2_48
 gboolean              g_dtls_connection_get_require_close_notify    (GDtlsConnection       *conn);
 
-GLIB_AVAILABLE_IN_2_48
+GLIB_DEPRECATED_IN_2_60
 void                  g_dtls_connection_set_rehandshake_mode        (GDtlsConnection       *conn,
                                                                      GTlsRehandshakeMode    mode);
-GLIB_AVAILABLE_IN_2_48
+GLIB_DEPRECATED_IN_2_60
 GTlsRehandshakeMode   g_dtls_connection_get_rehandshake_mode        (GDtlsConnection       *conn);
 
 GLIB_AVAILABLE_IN_2_48
diff --git a/gio/gioenums.h b/gio/gioenums.h
index a83fa71f1..a01532cfd 100644
--- a/gio/gioenums.h
+++ b/gio/gioenums.h
@@ -1593,6 +1593,10 @@ typedef enum {
  * g_tls_connection_set_rehandshake_mode().
  *
  * Since: 2.28
+ *
+ * Deprecated: 2.60. Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 typedef enum {
   G_TLS_REHANDSHAKE_NEVER,
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index 3dba7d7d9..26d1881c3 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -194,7 +194,8 @@ g_tls_connection_class_init (GTlsConnectionClass *klass)
                                                      G_TLS_REHANDSHAKE_SAFELY,
                                                      G_PARAM_READWRITE |
                                                      G_PARAM_CONSTRUCT |
-                                                     G_PARAM_STATIC_STRINGS));
+                                                     G_PARAM_STATIC_STRINGS |
+                                                     G_PARAM_DEPRECATED));
   /**
    * GTlsConnection:certificate:
    *
@@ -697,6 +698,10 @@ g_tls_connection_get_require_close_notify (GTlsConnection *conn)
  * software.
  *
  * Since: 2.28
+ *
+ * Deprecated: 2.60. Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 void
 g_tls_connection_set_rehandshake_mode (GTlsConnection       *conn,
@@ -719,6 +724,10 @@ g_tls_connection_set_rehandshake_mode (GTlsConnection       *conn,
  * Returns: @conn's rehandshaking mode
  *
  * Since: 2.28
+ *
+ * Deprecated: 2.60. Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 GTlsRehandshakeMode
 g_tls_connection_get_rehandshake_mode (GTlsConnection       *conn)
diff --git a/gio/gtlsconnection.h b/gio/gtlsconnection.h
index 9c038e29e..0cfcb5910 100644
--- a/gio/gtlsconnection.h
+++ b/gio/gtlsconnection.h
@@ -109,10 +109,10 @@ void                  g_tls_connection_set_require_close_notify    (GTlsConnecti
 GLIB_AVAILABLE_IN_ALL
 gboolean              g_tls_connection_get_require_close_notify    (GTlsConnection       *conn);
 
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_60
 void                  g_tls_connection_set_rehandshake_mode        (GTlsConnection       *conn,
                                                                    GTlsRehandshakeMode   mode);
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_60
 GTlsRehandshakeMode   g_tls_connection_get_rehandshake_mode        (GTlsConnection       *conn);
 
 GLIB_AVAILABLE_IN_ALL