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