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