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