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 any 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    * SSL 3.0 is no longer supported. See
 107    * g_tls_client_connection_set_use_ssl3() for details.
 108    *
 109    * Since: 2.28
 110    *
 111    * Deprecated: 2.56: SSL 3.0 is insecure.
 112    */
 113   g_object_interface_install_property (iface,
 114                                        g_param_spec_boolean ("use-ssl3",
 115                                                              P_("Use fallback"),
 116                                                              P_("Use fallback version of SSL/TLS rather than most recent version"),
 117                                                              FALSE,
 118                                                              G_PARAM_READWRITE |
 119                                                              G_PARAM_CONSTRUCT |
 120                                                              G_PARAM_STATIC_STRINGS |
 121                                                              G_PARAM_DEPRECATED));
 122
 123   /**
 124    * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
 125    *
 126    * A list of the distinguished names of the Certificate Authorities
 127    * that the server will accept client certificates signed by. If the
 128    * server requests a client certificate during the handshake, then
 129    * this property will be set after the handshake completes.
 130    *
 131    * Each item in the list is a #GByteArray which contains the complete
 132    * subject DN of the certificate authority.
 133    *
 134    * Since: 2.28
 135    */
 136   g_object_interface_install_property (iface,
 137                                        g_param_spec_pointer ("accepted-cas",
 138                                                              P_("Accepted CAs"),
 139                                                              P_("Distinguished names of the CAs the server accepts certificates from"),
 140                                                              G_PARAM_READABLE |
 141                                                              G_PARAM_STATIC_STRINGS));
 142 }
 143
 144 /**
 145  * g_tls_client_connection_new:
 146  * @base_io_stream: the #GIOStream to wrap
 147  * @server_identity: (nullable): the expected identity of the server
 148  * @error: #GError for error reporting, or %NULL to ignore.
 149  *
 150  * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
 151  * must have pollable input and output streams) which is assumed to
 152  * communicate with the server identified by @server_identity.
 153  *
 154  * See the documentation for #GTlsConnection:base-io-stream for restrictions
 155  * on when application code can run operations on the @base_io_stream after
 156  * this function has returned.
 157  *
 158  * Returns: (transfer full) (type GTlsClientConnection): the new
 159  * #GTlsClientConnection, or %NULL on error
 160  *
 161  * Since: 2.28
 162  */
 163 GIOStream *
 164 g_tls_client_connection_new (GIOStream           *base_io_stream,
 165                              GSocketConnectable  *server_identity,
 166                              GError             **error)
 167 {
 168   GObject *conn;
 169   GTlsBackend *backend;
 170
 171   backend = g_tls_backend_get_default ();
 172   conn = g_initable_new (g_tls_backend_get_client_connection_type (backend),
 173                          NULL, error,
 174                          "base-io-stream", base_io_stream,
 175                          "server-identity", server_identity,
 176                          NULL);
 177   return G_IO_STREAM (conn);
 178 }
 179
 180 /**
 181  * g_tls_client_connection_get_validation_flags:
 182  * @conn: the #GTlsClientConnection
 183  *
 184  * Gets @conn's validation flags
 185  *
 186  * Returns: the validation flags
 187  *
 188  * Since: 2.28
 189  */
 190 GTlsCertificateFlags
 191 g_tls_client_connection_get_validation_flags (GTlsClientConnection *conn)
 192 {
 193   GTlsCertificateFlags flags = 0;
 194
 195   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0);
 196
 197   g_object_get (G_OBJECT (conn), "validation-flags", &flags, NULL);
 198   return flags;
 199 }
 200
 201 /**
 202  * g_tls_client_connection_set_validation_flags:
 203  * @conn: the #GTlsClientConnection
 204  * @flags: the #GTlsCertificateFlags to use
 205  *
 206  * Sets @conn's validation flags, to override the default set of
 207  * checks performed when validating a server certificate. By default,
 208  * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
 209  *
 210  * Since: 2.28
 211  */
 212 void
 213 g_tls_client_connection_set_validation_flags (GTlsClientConnection  *conn,
 214                                               GTlsCertificateFlags   flags)
 215 {
 216   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn));
 217
 218   g_object_set (G_OBJECT (conn), "validation-flags", flags, NULL);
 219 }
 220
 221 /**
 222  * g_tls_client_connection_get_server_identity:
 223  * @conn: the #GTlsClientConnection
 224  *
 225  * Gets @conn's expected server identity
 226  *
 227  * Returns: (nullable) (transfer none): a #GSocketConnectable describing the
 228  * expected server identity, or %NULL if the expected identity is not
 229  * known.
 230  *
 231  * Since: 2.28
 232  */
 233 GSocketConnectable *
 234 g_tls_client_connection_get_server_identity (GTlsClientConnection *conn)
 235 {
 236   GSocketConnectable *identity = NULL;
 237
 238   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0);
 239
 240   g_object_get (G_OBJECT (conn), "server-identity", &identity, NULL);
 241   if (identity)
 242     g_object_unref (identity);
 243   return identity;
 244 }
 245
 246 /**
 247  * g_tls_client_connection_set_server_identity:
 248  * @conn: the #GTlsClientConnection
 249  * @identity: a #GSocketConnectable describing the expected server identity
 250  *
 251  * Sets @conn's expected server identity, which is used both to tell
 252  * servers on virtual hosts which certificate to present, and also
 253  * to let @conn know what name to look for in the certificate when
 254  * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
 255  *
 256  * Since: 2.28
 257  */
 258 void
 259 g_tls_client_connection_set_server_identity (GTlsClientConnection *conn,
 260                                              GSocketConnectable   *identity)
 261 {
 262   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn));
 263
 264   g_object_set (G_OBJECT (conn), "server-identity", identity, NULL);
 265 }
 266
 267 /**
 268  * g_tls_client_connection_get_use_ssl3:
 269  * @conn: the #GTlsClientConnection
 270  *
 271  * SSL 3.0 is no longer supported. See
 272  * g_tls_client_connection_set_use_ssl3() for details.
 273  *
 274  * Returns: %FALSE
 275  *
 276  * Since: 2.28
 277  *
 278  * Deprecated: 2.56: SSL 3.0 is insecure.
 279  */
 280 gboolean
 281 g_tls_client_connection_get_use_ssl3 (GTlsClientConnection *conn)
 282 {
 283   gboolean use_ssl3 = FALSE;
 284
 285   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), 0);
 286
 287   g_object_get (G_OBJECT (conn), "use-ssl3", &use_ssl3, NULL);
 288   return FALSE;
 289 }
 290
 291 /**
 292  * g_tls_client_connection_set_use_ssl3:
 293  * @conn: the #GTlsClientConnection
 294  * @use_ssl3: a #gboolean, ignored
 295  *
 296  * Since GLib 2.42.1, SSL 3.0 is no longer supported.
 297  *
 298  * From GLib 2.42.1 through GLib 2.62, this function could be used to
 299  * force use of TLS 1.0, the lowest-supported TLS protocol version at
 300  * the time. In the past, this was needed to connect to broken TLS
 301  * servers that exhibited protocol version intolerance. Such servers
 302  * are no longer common, and using TLS 1.0 is no longer considered
 303  * acceptable.
 304  *
 305  * Since GLib 2.64, this function does nothing.
 306  *
 307  * Since: 2.28
 308  *
 309  * Deprecated: 2.56: SSL 3.0 is insecure.
 310  */
 311 void
 312 g_tls_client_connection_set_use_ssl3 (GTlsClientConnection *conn,
 313                                       gboolean              use_ssl3)
 314 {
 315   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn));
 316
 317   g_object_set (G_OBJECT (conn), "use-ssl3", FALSE, NULL);
 318 }
 319
 320 /**
 321  * g_tls_client_connection_get_accepted_cas:
 322  * @conn: the #GTlsClientConnection
 323  *
 324  * Gets the list of distinguished names of the Certificate Authorities
 325  * that the server will accept certificates from. This will be set
 326  * during the TLS handshake if the server requests a certificate.
 327  * Otherwise, it will be %NULL.
 328  *
 329  * Each item in the list is a #GByteArray which contains the complete
 330  * subject DN of the certificate authority.
 331  *
 332  * Returns: (element-type GByteArray) (transfer full): the list of
 333  * CA DNs. You should unref each element with g_byte_array_unref() and then
 334  * the free the list with g_list_free().
 335  *
 336  * Since: 2.28
 337  */
 338 GList *
 339 g_tls_client_connection_get_accepted_cas (GTlsClientConnection *conn)
 340 {
 341   GList *accepted_cas = NULL;
 342
 343   g_return_val_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn), NULL);
 344
 345   g_object_get (G_OBJECT (conn), "accepted-cas", &accepted_cas, NULL);
 346   return accepted_cas;
 347 }
 348
 349 /**
 350  * g_tls_client_connection_copy_session_state:
 351  * @conn: a #GTlsClientConnection
 352  * @source: a #GTlsClientConnection
 353  *
 354  * Possibly copies session state from one connection to another, for use
 355  * in TLS session resumption. This is not normally needed, but may be
 356  * used when the same session needs to be used between different
 357  * endpoints, as is required by some protocols, such as FTP over TLS.
 358  * @source should have already completed a handshake and, since TLS 1.3,
 359  * it should have been used to read data at least once. @conn should not
 360  * have completed a handshake.
 361  *
 362  * It is not possible to know whether a call to this function will
 363  * actually do anything. Because session resumption is normally used
 364  * only for performance benefit, the TLS backend might not implement
 365  * this function. Even if implemented, it may not actually succeed in
 366  * allowing @conn to resume @source's TLS session, because the server
 367  * may not have sent a session resumption token to @source, or it may
 368  * refuse to accept the token from @conn. There is no way to know
 369  * whether a call to this function is actually successful.
 370  *
 371  * Using this function is not required to benefit from session
 372  * resumption. If the TLS backend supports session resumption, the
 373  * session will be resumed automatically if it is possible to do so
 374  * without weakening the privacy guarantees normally provided by TLS,
 375  * without need to call this function. For example, with TLS 1.3,
 376  * a session ticket will be automatically copied from any
 377  * #GTlsClientConnection that has previously received session tickets
 378  * from the server, provided a ticket is available that has not
 379  * previously been used for session resumption, since session ticket
 380  * reuse would be a privacy weakness. Using this function causes the
 381  * ticket to be copied without regard for privacy considerations.
 382  *
 383  * Since: 2.46
 384  */
 385 void
 386 g_tls_client_connection_copy_session_state (GTlsClientConnection *conn,
 387                                             GTlsClientConnection *source)
 388 {
 389   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (conn));
 390   g_return_if_fail (G_IS_TLS_CLIENT_CONNECTION (source));
 391   g_return_if_fail (G_TLS_CLIENT_CONNECTION_GET_INTERFACE (conn)->copy_session_state != NULL);
 392
 393   G_TLS_CLIENT_CONNECTION_GET_INTERFACE (conn)->copy_session_state (conn,
 394                                                                     source);
 395 }