gio/gtlsbackend.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, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #include "config.h"
  20 #include "glib.h"
  21
  22 #include "gtlsbackend.h"
  23 #include "gdummytlsbackend.h"
  24 #include "gioenumtypes.h"
  25 #include "giomodule-priv.h"
  26
  27 /**
  28  * SECTION:gtls
  29  * @title: TLS Overview
  30  * @short_description: TLS (aka SSL) support for GSocketConnection
  31  * @include: gio/gio.h
  32  *
  33  * #GTlsConnection and related classes provide TLS (Transport Layer
  34  * Security, previously known as SSL, Secure Sockets Layer) support for
  35  * gio-based network streams.
  36  *
  37  * In the simplest case, for a client connection, you can just set the
  38  * #GSocketClient:tls flag on a #GSocketClient, and then any
  39  * connections created by that client will have TLS negotiated
  40  * automatically, using appropriate default settings, and rejecting
  41  * any invalid or self-signed certificates (unless you change that
  42  * default by setting the #GSocketClient:tls-validation-flags
  43  * property). The returned object will be a #GTcpWrapperConnection,
  44  * which wraps the underlying #GTlsClientConnection.
  45  *
  46  * For greater control, you can create your own #GTlsClientConnection,
  47  * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
  48  * pollable input and output streams) and then connect to its signals,
  49  * such as #GTlsConnection::accept-certificate, before starting the
  50  * handshake.
  51  *
  52  * Server-side TLS is similar, using #GTlsServerConnection. At the
  53  * moment, there is no support for automatically wrapping server-side
  54  * connections in the way #GSocketClient does for client-side
  55  * connections.
  56  */
  57
  58 /**
  59  * SECTION:gtlsbackend
  60  * @title: GTlsBackend
  61  * @short_description: TLS backend implementation
  62  * @include: gio/gio.h
  63  */
  64
  65 /**
  66  * GTlsBackend:
  67  *
  68  * TLS (Transport Layer Security, aka SSL) backend. This is an
  69  * internal type used to coordinate the different classes implemented
  70  * by a TLS backend.
  71  *
  72  * Since: 2.28
  73  */
  74
  75 G_DEFINE_INTERFACE (GTlsBackend, g_tls_backend, G_TYPE_OBJECT);
  76
  77 static void
  78 g_tls_backend_default_init (GTlsBackendInterface *iface)
  79 {
  80 }
  81
  82 /**
  83  * g_tls_backend_get_default:
  84  *
  85  * Gets the default #GTlsBackend for the system.
  86  *
  87  * Returns: (transfer none): a #GTlsBackend
  88  *
  89  * Since: 2.28
  90  */
  91 GTlsBackend *
  92 g_tls_backend_get_default (void)
  93 {
  94   return _g_io_module_get_default (G_TLS_BACKEND_EXTENSION_POINT_NAME,
  95                                    "GIO_USE_TLS", NULL);
  96 }
  97
  98 /**
  99  * g_tls_backend_supports_tls:
 100  * @backend: the #GTlsBackend
 101  *
 102  * Checks if TLS is supported; if this returns %FALSE for the default
 103  * #GTlsBackend, it means no "real" TLS backend is available.
 104  *
 105  * Returns: whether or not TLS is supported
 106  *
 107  * Since: 2.28
 108  */
 109 gboolean
 110 g_tls_backend_supports_tls (GTlsBackend *backend)
 111 {
 112   if (G_TLS_BACKEND_GET_INTERFACE (backend)->supports_tls)
 113     return G_TLS_BACKEND_GET_INTERFACE (backend)->supports_tls (backend);
 114   else if (G_IS_DUMMY_TLS_BACKEND (backend))
 115     return FALSE;
 116   else
 117     return TRUE;
 118 }
 119
 120 /**
 121  * g_tls_backend_get_default_database:
 122  * @backend: the #GTlsBackend
 123  *
 124  * Gets the default #GTlsDatabase used to verify TLS connections.
 125  *
 126  * Returns: (transfer full): the default database, which should be
 127  *               unreffed when done.
 128  *
 129  * Since: 2.30
 130  */
 131 GTlsDatabase *
 132 g_tls_backend_get_default_database (GTlsBackend *backend)
 133 {
 134   g_return_val_if_fail (G_IS_TLS_BACKEND (backend), NULL);
 135
 136   /* This method was added later, so accept the (remote) possibility it can be NULL */
 137   if (!G_TLS_BACKEND_GET_INTERFACE (backend)->get_default_database)
 138     return NULL;
 139
 140   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_default_database (backend);
 141 }
 142
 143 /**
 144  * g_tls_backend_get_certificate_type:
 145  * @backend: the #GTlsBackend
 146  *
 147  * Gets the #GType of @backend's #GTlsCertificate implementation.
 148  *
 149  * Returns: the #GType of @backend's #GTlsCertificate
 150  *   implementation.
 151  *
 152  * Since: 2.28
 153  */
 154 GType
 155 g_tls_backend_get_certificate_type (GTlsBackend *backend)
 156 {
 157   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_certificate_type ();
 158 }
 159
 160 /**
 161  * g_tls_backend_get_client_connection_type:
 162  * @backend: the #GTlsBackend
 163  *
 164  * Gets the #GType of @backend's #GTlsClientConnection implementation.
 165  *
 166  * Returns: the #GType of @backend's #GTlsClientConnection
 167  *   implementation.
 168  *
 169  * Since: 2.28
 170  */
 171 GType
 172 g_tls_backend_get_client_connection_type (GTlsBackend *backend)
 173 {
 174   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_client_connection_type ();
 175 }
 176
 177 /**
 178  * g_tls_backend_get_server_connection_type:
 179  * @backend: the #GTlsBackend
 180  *
 181  * Gets the #GType of @backend's #GTlsServerConnection implementation.
 182  *
 183  * Returns: the #GType of @backend's #GTlsServerConnection
 184  *   implementation.
 185  *
 186  * Since: 2.28
 187  */
 188 GType
 189 g_tls_backend_get_server_connection_type (GTlsBackend *backend)
 190 {
 191   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_server_connection_type ();
 192 }
 193
 194 /**
 195  * g_tls_backend_get_file_database_type:
 196  * @backend: the #GTlsBackend
 197  *
 198  * Gets the #GType of @backend's #GTlsFileDatabase implementation.
 199  *
 200  * Returns: the #GType of backend's #GTlsFileDatabase implementation.
 201  *
 202  * Since: 2.30
 203  */
 204 GType
 205 g_tls_backend_get_file_database_type (GTlsBackend *backend)
 206 {
 207   g_return_val_if_fail (G_IS_TLS_BACKEND (backend), 0);
 208
 209   /* This method was added later, so accept the (remote) possibility it can be NULL */
 210   if (!G_TLS_BACKEND_GET_INTERFACE (backend)->get_file_database_type)
 211     return 0;
 212
 213   return G_TLS_BACKEND_GET_INTERFACE (backend)->get_file_database_type ();
 214 }