Merge branch 'mcatanzaro/tls1.3-handshake' into 'master'

Deprecate TLS rehandshaking

See merge request GNOME/glib!478

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",
@@ -171,7 +175,8 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
                                                           G_TLS_REHANDSHAKE_NEVER,
                                                           G_PARAM_READWRITE |
                                                           G_PARAM_CONSTRUCT |
-                                                          G_PARAM_STATIC_STRINGS));
+                                                          G_PARAM_STATIC_STRINGS |
+                                                          G_PARAM_DEPRECATED));
   /**
    * GDtlsConnection:certificate:
    *
@@ -597,6 +602,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 +665,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.

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

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,

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)
@@ -756,11 +765,15 @@ g_tls_connection_get_rehandshake_mode (GTlsConnection       *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_tls_connection_handshake() later on to
+ *
- * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, the
+ * If TLS 1.2 or older is in use, you may call
- * behavior is undefined but guaranteed to be reasonable and
+ * g_tls_connection_handshake() after the initial handshake to
- * nondestructive, so most older code should be expected to continue to
+ * rehandshake; however, this usage is deprecated because rehandshaking
- * work without changes.
+ * 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.
  *
  * #GTlsConnection::accept_certificate may be emitted during the
  * handshake.

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