gio/gtlsclientconnection.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2010 Red Hat, Inc
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "config.h"
  22 #include "glib.h"
  23
  24 #include "gtlsclientconnection.h"
  25 #include "ginitable.h"
  26 #include "gioenumtypes.h"
  27 #include "gio-marshal.h"
  28 #include "gsocket.h"
  29 #include "gsocketconnectable.h"
  30 #include "gtlsbackend.h"
  31 #include "gtlscertificate.h"
  32 #include "glibintl.h"
  33
  34 /**
  35  * SECTION:gtlsclientconnection
  36  * @short_description: TLS client-side connection
  37  * @include: gio/gio.h
  38  *
  39  * #GTlsClientConnection is the client-side subclass of
  40  * #GTlsConnection, representing a client-side TLS connection.
  41  *
  42  * Since: 2.28
  43  */
  44
  45 /**
  46  * GTlsClientConnection:
  47  *
  48  * Abstract base class for the backend-specific client connection
  49  * type.
  50  *
  51  * Since: 2.28
  52  */
  53
  54 G_DEFINE_INTERFACE (GTlsClientConnection, g_tls_client_connection, G_TYPE_TLS_CONNECTION)
  55
  56 static void
  57 g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
  58 {
  59   /**
  60    * GTlsClientConnection:validation-flags:
  61    *
  62    * What steps to perform when validating a certificate received from
  63    * a server. Server certificates that fail to validate in all of the
  64    * ways indicated here will be rejected unless the application
  65    * overrides the default via #GTlsConnection::accept-certificate.
  66    *
  67    * Since: 2.28
  68    */
  69   g_object_interface_install_property (iface,
  70                                        g_param_spec_flags ("validation-flags",
  71                                                            P_("Validation flags"),
  72                                                            P_("What certificate validation to perform"),
  73                                                            G_TYPE_TLS_CERTIFICATE_FLAGS,
  74                                                            G_TLS_CERTIFICATE_VALIDATE_ALL,
  75                                                            G_PARAM_READWRITE |
  76                                                            G_PARAM_CONSTRUCT |
  77                                                            G_PARAM_STATIC_STRINGS));
  78
  79   /**
  80    * GTlsClientConnection:server-identity:
  81    *
  82    * A #GSocketConnectable describing the identity of the server that
  83    * is expected on the other end of the connection.
  84    *
  85    * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
  86    * #GTlsClientConnection:validation-flags, this object will be used
  87    * to determine the expected identify of the remote end of the
  88    * connection; if #GTlsClientConnection:server-identity is not set,
  89    * or does not match the identity presented by the server, then the
  90    * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
  91    *
  92    * In addition to its use in verifying the server certificate,
  93    * this is also used to give a hint to the server about what
  94    * certificate we expect, which is useful for servers that serve
  95    * virtual hosts.
  96    *
  97    * Since: 2.28
  98    */
  99   g_object_interface_install_property (iface,
 100                                        g_param_spec_object ("server-identity",
 101                                                             P_("Server identity"),
 102                                                             P_("GSocketConnectable identifying the server"),
 103                                                             G_TYPE_SOCKET_CONNECTABLE,
 104                                                             G_PARAM_READWRITE |
 105                                                             G_PARAM_CONSTRUCT |
 106                                                             G_PARAM_STATIC_STRINGS));
 107
 108   /**
 109    * GTlsClientConnection:use-ssl3:
 110    *
 111    * If %TRUE, tells the connection to use SSL 3.0 rather than trying
 112    * to negotiate the best version of TLS or SSL to use. This can be
 113    * used when talking to servers that don't implement version
 114    * negotiation correctly and therefore refuse to handshake at all with
 115    * a "modern" TLS handshake.
 116    *
 117    * Since: 2.28
 118    */
 119   g_object_interface_install_property (iface,
 120                                        g_param_spec_boolean ("use-ssl3",
 121                                                              P_("Use SSL3"),
 122                                                              P_("Use SSL 3.0 rather than trying to use TLS 1.x"),
 123                                                              FALSE,
 124                                                              G_PARAM_READWRITE |
 125                                                              G_PARAM_CONSTRUCT |
 126                                                              G_PARAM_STATIC_STRINGS));
 127
 128   /**
 129    * GTlsClientConnection:accepted-cas:
 130    *
 131    * A list of the distinguished names of the Certificate Authorities
 132    * that the server will accept client certificates signed by. If the
 133    * server requests a client certificate during the handshake, then
 134    * this property will be set after the handshake completes.
 135    *
 136    * Since: 2.28
 137    */
 138   g_object_interface_install_property (iface,
 139                                        g_param_spec_boxed ("accepted-cas",
 140                                                            P_("Accepted CAs"),
 141                                                            P_("Distinguished names of the CAs the server accepts certificates from"),
 142                                                            G_TYPE_STRV,
 143                                                            G_PARAM_READABLE |
 144                                                            G_PARAM_STATIC_STRINGS));
 145 }
 146
 147 /**
 148  * g_tls_client_connection_new:
 149  * @base_io_stream: the #GIOStream to wrap
 150  * @server_identity: (allow-none): the expected identity of the server
 151  * @error: #GError for error reporting, or %NULL to ignore.
 152  *
 153  * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
 154  * must have pollable input and output streams) which is assumed to
 155  * communicate with the server identified by @server_identity.
 156  *
 157  * Return value: the new #GTlsClientConnection, or %NULL on error
 158  *
 159  * Since: 2.28
 160  */
 161 GIOStream *
 162 g_tls_client_connection_new (GIOStream           *base_io_stream,
 163                              GSocketConnectable  *server_identity,
 164                              GError             **error)
 165 {
 166   GObject *conn;
 167   GTlsBackend *backend;
 168
 169   backend = g_tls_backend_get_default ();
 170   conn = g_initable_new (g_tls_backend_get_client_connection_type (backend),
 171                          NULL, error,
 172                          "base-io-stream", base_io_stream,
 173                          "server-identity", server_identity,
 174                          NULL);
 175   return G_IO_STREAM (conn);
 176 }
 177
 178 /**
 179  * g_tls_client_connection_get_validation_flags:
 180  * @conn: the #GTlsClientConnection
 181  *
 182  * Gets @conn's validation flags
 183  *
 184  * Return value: the validation flags
 185  *
 186  * Since: 2.28
 187  */
 188 GTlsCertificateFlags
 189 g_tls_client_connection_get_validation_flags (GTlsClientConnection *conn)
 190 {
 191   GTlsCertificateFlags flags = 0;
 192
 193   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0);
 194
 195   g_object_get (G_OBJECT (conn), "validation-flags", &flags, NULL);
 196   return flags;
 197 }
 198
 199 /**
 200  * g_tls_client_connection_set_validation_flags:
 201  * @conn: the #GTlsClientConnection
 202  * @flags: the #GTlsCertificateFlags to use
 203  *
 204  * Sets @conn's validation flags, to override the default set of
 205  * checks performed when validating a server certificate. By default,
 206  * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
 207  *
 208  * Since: 2.28
 209  */
 210 void
 211 g_tls_client_connection_set_validation_flags (GTlsClientConnection  *conn,
 212                                               GTlsCertificateFlags   flags)
 213 {
 214   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn));
 215
 216   g_object_set (G_OBJECT (conn), "validation-flags", flags, NULL);
 217 }
 218
 219 /**
 220  * g_tls_client_connection_get_server_identity:
 221  * @conn: the #GTlsClientConnection
 222  *
 223  * Gets @conn's expected server identity
 224  *
 225  * Return value: a #GSocketConnectable describing the
 226  * expected server identity, or %NULL if the expected identity is not
 227  * known.
 228  *
 229  * Since: 2.28
 230  */
 231 GSocketConnectable *
 232 g_tls_client_connection_get_server_identity (GTlsClientConnection *conn)
 233 {
 234   GSocketConnectable *identity = NULL;
 235
 236   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0);
 237
 238   g_object_get (G_OBJECT (conn), "server-identity", &identity, NULL);
 239   if (identity)
 240     g_object_unref (identity);
 241   return identity;
 242 }
 243
 244 /**
 245  * g_tls_client_connection_set_server_identity:
 246  * @conn: the #GTlsClientConnection
 247  * @identity: a #GSocketConnectable describing the expected server identity
 248  *
 249  * Sets @conn's expected server identity, which is used both to tell
 250  * servers on virtual hosts which certificate to present, and also
 251  * to let @conn know what name to look for in the certificate when
 252  * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
 253  *
 254  * Since: 2.28
 255  */
 256 void
 257 g_tls_client_connection_set_server_identity (GTlsClientConnection *conn,
 258                                              GSocketConnectable   *identity)
 259 {
 260   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn));
 261
 262   g_object_set (G_OBJECT (conn), "server-identity", identity, NULL);
 263 }
 264
 265 /**
 266  * g_tls_client_connection_get_use_ssl3:
 267  * @conn: the #GTlsClientConnection
 268  *
 269  * Gets whether @conn will use SSL 3.0 rather than the
 270  * highest-supported version of TLS; see
 271  * g_tls_client_connection_set_use_ssl3().
 272  *
 273  * Return value: whether @conn will use SSL 3.0
 274  *
 275  * Since: 2.28
 276  */
 277 gboolean
 278 g_tls_client_connection_get_use_ssl3 (GTlsClientConnection *conn)
 279 {
 280   gboolean use_ssl3 = FALSE;
 281
 282   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0);
 283
 284   g_object_get (G_OBJECT (conn), "use-ssl3", &use_ssl3, NULL);
 285   return use_ssl3;
 286 }
 287
 288 /**
 289  * g_tls_client_connection_set_use_ssl3:
 290  * @conn: the #GTlsClientConnection
 291  * @use_ssl3: whether to use SSL 3.0
 292  *
 293  * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
 294  * trying to properly negotiate the right version of TLS or SSL to use.
 295  * This can be used when talking to servers that do not implement the
 296  * fallbacks correctly and which will therefore fail to handshake with
 297  * a "modern" TLS handshake attempt.
 298  *
 299  * Since: 2.28
 300  */
 301 void
 302 g_tls_client_connection_set_use_ssl3 (GTlsClientConnection *conn,
 303                                       gboolean              use_ssl3)
 304 {
 305   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn));
 306
 307   g_object_set (G_OBJECT (conn), "use-ssl3", use_ssl3, NULL);
 308 }
 309
 310 /**
 311  * g_tls_client_connection_get_accepted_cas:
 312  * @conn: the #GTlsClientConnection
 313  *
 314  * Gets the list of distinguished names of the Certificate Authorities
 315  * that the server will accept certificates from. This will be set
 316  * during the TLS handshake if the server requests a certificate.
 317  * Otherwise, it will be %NULL.
 318  *
 319  * Return value: (transfer full) (array zero-terminated=1): the list
 320  * of CA names, which you must free (eg, with g_strfreev()).
 321  *
 322  * Since: 2.28
 323  */
 324 char **
 325 g_tls_client_connection_get_accepted_cas (GTlsClientConnection *conn)
 326 {
 327   char **accepted_cas = NULL;
 328
 329   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), NULL);
 330
 331   g_object_get (G_OBJECT (conn), "accepted-cas", &accepted_cas, NULL);
 332   return accepted_cas;
 333 }