From 94a99ae917bceaf48aeff6822c78408f27a1e228 Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Fri, 27 Jul 2018 08:16:25 -0500 Subject: [PATCH 1/2] Update documentation of g_tls_connection_handshake Rehandshaking is not a thing in TLS 1.3. In that case, g_tls_connection_handshake() should instead perform a re-key. --- gio/gtlsconnection.c | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c index e13d98614..b0353af9d 100644 --- a/gio/gtlsconnection.c +++ b/gio/gtlsconnection.c @@ -674,7 +674,8 @@ g_tls_connection_get_require_close_notify (GTlsConnection *conn) * @conn: a #GTlsConnection * @mode: the rehandshaking mode * - * Sets how @conn behaves with respect to rehandshaking requests. + * Sets how @conn behaves with respect to rehandshaking requests, when + * TLS 1.2 or older is in use. * * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to * rehandshake after the initial handshake is complete. (For a client, @@ -756,7 +757,8 @@ g_tls_connection_get_rehandshake_mode (GTlsConnection *conn) * 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 - * renegotiate parameters (encryption methods, etc) with the client. + * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, this will + * instead perform a rekey. * * #GTlsConnection::accept_certificate may be emitted during the * handshake. From 08fe93589ece786f49cf7d728b8dea618c7f5251 Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Sat, 4 Aug 2018 16:33:28 -0500 Subject: [PATCH 2/2] Update documentation of g_tls_client_connection_set_use_ssl3() We now send the fallback SCSV, meaning use of this function will cause modern servers to immediately terminate the connection, so let's warn API users to expect that behavior and be crystal clear that this function should only be used as a fallback when a normal connection attempt has already failed. Also, the documentation is mostly duplicated between the property and the function, so let's just reference the function documentation from the property. --- gio/gtlsclientconnection.c | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/gio/gtlsclientconnection.c b/gio/gtlsclientconnection.c index f80c62572..b38fad630 100644 --- a/gio/gtlsclientconnection.c +++ b/gio/gtlsclientconnection.c @@ -105,14 +105,7 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface) * * If %TRUE, forces the connection to use a fallback version of TLS * or SSL, rather than trying to negotiate the best version of TLS - * to use. This can be used when talking to servers that don't - * implement version negotiation correctly and therefore refuse to - * handshake at all with a modern TLS handshake. - * - * Despite the property name, the fallback version is usually not - * SSL 3.0, because SSL 3.0 is generally disabled by the #GTlsBackend. - * #GTlsClientConnection will use the next-highest available version - * as the fallback version. + * to use. See g_tls_client_connection_set_use_ssl3(). * * Since: 2.28 * @@ -304,14 +297,19 @@ g_tls_client_connection_get_use_ssl3 (GTlsClientConnection *conn) * @conn: the #GTlsClientConnection * @use_ssl3: whether to use the lowest-supported protocol version * - * If @use_ssl3 is %TRUE, this forces @conn to use the lowest-supported - * TLS protocol version rather than trying to properly negotiate the - * highest mutually-supported protocol version with the peer. This can - * be used when talking to broken TLS servers that exhibit protocol - * version intolerance. + * Since 2.42.1, if @use_ssl3 is %TRUE, this forces @conn to use the + * lowest-supported TLS protocol version rather than trying to properly + * negotiate the highest mutually-supported protocol version with the + * peer. Be aware that SSL 3.0 is generally disabled by the + * #GTlsBackend, so the lowest-supported protocol version is probably + * not SSL 3.0. * - * Be aware that SSL 3.0 is generally disabled by the #GTlsBackend, so - * the lowest-supported protocol version is probably not SSL 3.0. + * Since 2.58, this may additionally cause an RFC 7507 fallback SCSV to + * be sent to the server, causing modern TLS servers to immediately + * terminate the connection. You should generally only use this function + * if you need to connect to broken servers that exhibit TLS protocol + * version intolerance, and when an initial attempt to connect to a + * server normally has already failed. * * Since: 2.28 *