gio/gtlsbackend.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2010 Red Hat, Inc
   4  * Copyright © 2015 Collabora, Ltd.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General
  17  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #include "config.h"
  21 #include "glib.h"
  22
  23 #include "gtlsbackend.h"
  24 #include "gdummytlsbackend.h"
  25 #include "gioenumtypes.h"
  26 #include "giomodule-priv.h"
  27
  28 /**
  29  * SECTION:gtls
  30  * @title: TLS Overview
  31  * @short_description: TLS (aka SSL) support for GSocketConnection
  32  * @include: gio/gio.h
  33  *
  34  * #GTlsConnection and related classes provide TLS (Transport Layer
  35  * Security, previously known as SSL, Secure Sockets Layer) support for
  36  * gio-based network streams.
  37  *
  38  * #GDtlsConnection and related classes provide DTLS (Datagram TLS) support for
  39  * GIO-based network sockets, using the #GDatagramBased interface. The TLS and
  40  * DTLS APIs are almost identical, except TLS is stream-based and DTLS is
  41  * datagram-based. They share certificate and backend infrastructure.
  42  *
  43  * In the simplest case, for a client TLS connection, you can just set the
  44  * #GSocketClient:tls flag on a #GSocketClient, and then any
  45  * connections created by that client will have TLS negotiated
  46  * automatically, using appropriate default settings, and rejecting
  47  * any invalid or self-signed certificates (unless you change that
  48  * default by setting the #GSocketClient:tls-validation-flags
  49  * property). The returned object will be a #GTcpWrapperConnection,
  50  * which wraps the underlying #GTlsClientConnection.
  51  *
  52  * For greater control, you can create your own #GTlsClientConnection,
  53  * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
  54  * pollable input and output streams) and then connect to its signals,
  55  * such as #GTlsConnection::accept-certificate, before starting the
  56  * handshake.
  57  *
  58  * Server-side TLS is similar, using #GTlsServerConnection. At the
  59  * moment, there is no support for automatically wrapping server-side
  60  * connections in the way #GSocketClient does for client-side
  61  * connections.
  62  */
  63
  64 /**
  65  * SECTION:gtlsbackend
  66  * @title: GTlsBackend
  67  * @short_description: TLS backend implementation
  68  * @include: gio/gio.h
  69  *
  70  * TLS (Transport Layer Security, aka SSL) and DTLS backend.
  71  *
  72  * Since: 2.28
  73  */
  74
  75 /**
  76  * GTlsBackend:
  77  *
  78  * TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an
  79  * internal type used to coordinate the different classes implemented
  80  * by a TLS backend.
  81  *
  82  * Since: 2.28
  83  */
  84
  85 G_DEFINE_INTERFACE (GTlsBackend, g_tls_backend, G_TYPE_OBJECT)
  86
  87 static void
  88 g_tls_backend_default_init (GTlsBackendInterface *iface)
  89 {
  90 }
  91
  92 /**
  93  * g_tls_backend_get_default:
  94  *
  95  * Gets the default #GTlsBackend for the system.
  96  *
  97  * Returns: (transfer none): a #GTlsBackend
  98  *
  99  * Since: 2.28
 100  */
 101 GTlsBackend *
 102 g_tls_backend_get_default (void)
 103 {
 104   return _g_io_module_get_default (G_TLS_BACKEND_EXTENSION_POINT_NAME,
 105                                    "GIO_USE_TLS", NULL);
 106 }
 107
 108 /**
 109  * g_tls_backend_supports_tls:
 110  * @backend: the #GTlsBackend
 111  *
 112  * Checks if TLS is supported; if this returns %FALSE for the default
 113  * #GTlsBackend, it means no "real" TLS backend is available.
 114  *
 115  * Returns: whether or not TLS is supported
 116  *
 117  * Since: 2.28
 118  */
 119 gboolean
 120 g_tls_backend_supports_tls (GTlsBackend *backend)
 121 {
 122   if (G_TLS_BACKEND_GET_INTERFACE (backend)->supports_tls)
 123     return G_TLS_BACKEND_GET_INTERFACE (backend)->supports_tls (backend);
 124   else if (G_IS_DUMMY_TLS_BACKEND (backend))
 125     return FALSE;
 126   else
 127     return TRUE;
 128 }
 129
 130 /**
 131  * g_tls_backend_supports_dtls:
 132  * @backend: the #GTlsBackend
 133  *
 134  * Checks if DTLS is supported. DTLS support may not be available even if TLS
 135  * support is available, and vice-versa.
 136  *
 137  * Returns: whether DTLS is supported
 138  *
 139  * Since: 2.48
 140  */
 141 gboolean
 142 g_tls_backend_supports_dtls (GTlsBackend *backend)
 143 {
 144   if (G_TLS_BACKEND_GET_INTERFACE (backend)->supports_dtls)
 145     return G_TLS_BACKEND_GET_INTERFACE (backend)->supports_dtls (backend);
 146
 147   return FALSE;
 148 }
 149
 150 /**
 151  * g_tls_backend_get_default_database:
 152  * @backend: the #GTlsBackend
 153  *
 154  * Gets the default #GTlsDatabase used to verify TLS connections.
 155  *
 156  * Returns: (transfer full): the default database, which should be
 157  *               unreffed when done.
 158  *
 159  * Since: 2.30
 160  */
 161 GTlsDatabase *
 162 g_tls_backend_get_default_database (GTlsBackend *backend)
 163 {
 164   g_return_val_if_fail (G_IS_TLS_BACKEND (backend), NULL);
 165
 166   /* This method was added later, so accept the (remote) possibility it can be NULL */
 167   if (!G_TLS_BACKEND_GET_INTERFACE (backend)->get_default_database)
 168     return NULL;
 169
 170   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_default_database (backend);
 171 }
 172
 173 /**
 174  * g_tls_backend_get_certificate_type:
 175  * @backend: the #GTlsBackend
 176  *
 177  * Gets the #GType of @backend's #GTlsCertificate implementation.
 178  *
 179  * Returns: the #GType of @backend's #GTlsCertificate
 180  *   implementation.
 181  *
 182  * Since: 2.28
 183  */
 184 GType
 185 g_tls_backend_get_certificate_type (GTlsBackend *backend)
 186 {
 187   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_certificate_type ();
 188 }
 189
 190 /**
 191  * g_tls_backend_get_client_connection_type:
 192  * @backend: the #GTlsBackend
 193  *
 194  * Gets the #GType of @backend's #GTlsClientConnection implementation.
 195  *
 196  * Returns: the #GType of @backend's #GTlsClientConnection
 197  *   implementation.
 198  *
 199  * Since: 2.28
 200  */
 201 GType
 202 g_tls_backend_get_client_connection_type (GTlsBackend *backend)
 203 {
 204   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_client_connection_type ();
 205 }
 206
 207 /**
 208  * g_tls_backend_get_server_connection_type:
 209  * @backend: the #GTlsBackend
 210  *
 211  * Gets the #GType of @backend's #GTlsServerConnection implementation.
 212  *
 213  * Returns: the #GType of @backend's #GTlsServerConnection
 214  *   implementation.
 215  *
 216  * Since: 2.28
 217  */
 218 GType
 219 g_tls_backend_get_server_connection_type (GTlsBackend *backend)
 220 {
 221   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_server_connection_type ();
 222 }
 223
 224 /**
 225  * g_tls_backend_get_dtls_client_connection_type:
 226  * @backend: the #GTlsBackend
 227  *
 228  * Gets the #GType of @backend’s #GDtlsClientConnection implementation.
 229  *
 230  * Returns: the #GType of @backend’s #GDtlsClientConnection
 231  *   implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
 232  *
 233  * Since: 2.48
 234  */
 235 GType
 236 g_tls_backend_get_dtls_client_connection_type (GTlsBackend *backend)
 237 {
 238   GTlsBackendInterface *iface;
 239
 240   g_return_val_if_fail (G_IS_TLS_BACKEND (backend), G_TYPE_INVALID);
 241
 242   iface = G_TLS_BACKEND_GET_INTERFACE (backend);
 243   if (iface->get_dtls_client_connection_type == NULL)
 244     return G_TYPE_INVALID;
 245
 246   return iface->get_dtls_client_connection_type ();
 247 }
 248
 249 /**
 250  * g_tls_backend_get_dtls_server_connection_type:
 251  * @backend: the #GTlsBackend
 252  *
 253  * Gets the #GType of @backend’s #GDtlsServerConnection implementation.
 254  *
 255  * Returns: the #GType of @backend’s #GDtlsServerConnection
 256  *   implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
 257  *
 258  * Since: 2.48
 259  */
 260 GType
 261 g_tls_backend_get_dtls_server_connection_type (GTlsBackend *backend)
 262 {
 263   GTlsBackendInterface *iface;
 264
 265   g_return_val_if_fail (G_IS_TLS_BACKEND (backend), G_TYPE_INVALID);
 266
 267   iface = G_TLS_BACKEND_GET_INTERFACE (backend);
 268   if (iface->get_dtls_server_connection_type == NULL)
 269     return G_TYPE_INVALID;
 270
 271   return iface->get_dtls_server_connection_type ();
 272 }
 273
 274 /**
 275  * g_tls_backend_get_file_database_type:
 276  * @backend: the #GTlsBackend
 277  *
 278  * Gets the #GType of @backend's #GTlsFileDatabase implementation.
 279  *
 280  * Returns: the #GType of backend's #GTlsFileDatabase implementation.
 281  *
 282  * Since: 2.30
 283  */
 284 GType
 285 g_tls_backend_get_file_database_type (GTlsBackend *backend)
 286 {
 287   g_return_val_if_fail (G_IS_TLS_BACKEND (backend), 0);
 288
 289   /* This method was added later, so accept the (remote) possibility it can be NULL */
 290   if (!G_TLS_BACKEND_GET_INTERFACE (backend)->get_file_database_type)
 291     return 0;
 292
 293   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_file_database_type ();
 294 }