From 2031e37dfca0ac8543bb06c0648c28b2b92ee701 Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Sat, 17 Nov 2018 11:14:27 -0600 Subject: [PATCH] Update documentation of g_tls_connection_handshake() one last time Let's entirely deprecate calling this function for rehandshaking. The current documentation is OK, but guarantees defined behavior (to attempt a rehandshake) when TLS 1.2 is in use. But there's no way to force TLS 1.2, and also no way to check which version of TLS is in use. I really should have deprecated use of this function for rehandshaking entirely last time I updated it. Fortunately, there should be no compatibility risk for existing code, because rehandshaking has no visible effects at the API level. --- gio/gdtlsconnection.c | 11 +++++++++-- gio/gtlsconnection.c | 14 +++++++++----- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/gio/gdtlsconnection.c b/gio/gdtlsconnection.c index cbcb720dc..a51910eb5 100644 --- a/gio/gdtlsconnection.c +++ b/gio/gdtlsconnection.c @@ -656,8 +656,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/gtlsconnection.c b/gio/gtlsconnection.c index 4364c1253..3dba7d7d9 100644 --- a/gio/gtlsconnection.c +++ b/gio/gtlsconnection.c @@ -756,11 +756,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 - * behavior is undefined but guaranteed to be reasonable and - * nondestructive, so most older code should be expected to continue to - * work without changes. + * + * If TLS 1.2 or older is in use, you may call + * g_tls_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. * * #GTlsConnection::accept_certificate may be emitted during the * handshake.