[glib] GTlsClientConnection: loosen the semantics of "use-ssl3"

[Dan Winship <danw src gnome org>]

commit 7f5c862e166a6f288d8d0ec2622685316f64b87c
Author: Dan Winship <danw gnome org>
Date:   Sat Nov 22 10:54:41 2014 -0500

    GTlsClientConnection: loosen the semantics of "use-ssl3"
    
    If SSL 3.0 has been disabled (at the host, application, or library
    level), then the "use-ssl3" property becomes a "fail-immediately"
    property.
    
    Despite the name, the point of the property wasn't really specifically
    to use SSL 3.0; it was to allow fallback when talking to broken
    servers that do SSL/TLS negotiation incorrectly and break when they
    see unexpectedly-high version numbers. So if we can't fall back to SSL
    3.0, then the "use-ssl3" property should fall back to TLS 1.0 instead
    (since there are hosts that will reject a TLS 1.2 handshake, but
    accept a TLS 1.0 one).
    
    glib-networking is being updated to implement that behavior, so update
    the documentation here.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=738633

 gio/gtlsclientconnection.c |   19 ++++++++++++-------
 1 files changed, 12 insertions(+), 7 deletions(-)
---
diff --git a/gio/gtlsclientconnection.c b/gio/gtlsclientconnection.c
index 5d2a17d..e9e1e54 100644
--- a/gio/gtlsclientconnection.c
+++ b/gio/gtlsclientconnection.c
@@ -103,18 +103,23 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
   /**
    * GTlsClientConnection:use-ssl3:
    *
-   * If %TRUE, tells the connection to use SSL 3.0 rather than trying
-   * to negotiate the best version of TLS or SSL 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.
+   * If %TRUE, tells 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 not
+   * necessarily SSL 3.0; if SSL 3.0 has been disabled, the
+   * #GTlsClientConnection will use the next highest available version
+   * (normally TLS 1.0) as the fallback version.
    *
    * Since: 2.28
    */
   g_object_interface_install_property (iface,
                                       g_param_spec_boolean ("use-ssl3",
-                                                            P_("Use SSL3"),
-                                                            P_("Use SSL 3.0 rather than trying to use TLS 
1.x"),
+                                                            P_("Use fallback"),
+                                                            P_("Use fallback version of SSL/TLS rather than 
most recent version"),
                                                             FALSE,
                                                             G_PARAM_READWRITE |
                                                             G_PARAM_CONSTRUCT |