gio/gdtlsclientconnection.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 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 "gdtlsclientconnection.h"
  24 #include "ginitable.h"
  25 #include "gioenumtypes.h"
  26 #include "gsocket.h"
  27 #include "gsocketconnectable.h"
  28 #include "gtlsbackend.h"
  29 #include "gtlscertificate.h"
  30 #include "glibintl.h"
  31
  32 /**
  33  * SECTION:gdtlsclientconnection
  34  * @short_description: DTLS client-side connection
  35  * @include: gio/gio.h
  36  *
  37  * #GDtlsClientConnection is the client-side subclass of
  38  * #GDtlsConnection, representing a client-side DTLS connection.
  39  *
  40  * Since: 2.48
  41  */
  42
  43 /**
  44  * GDtlsClientConnection:
  45  *
  46  * Abstract base class for the backend-specific client connection
  47  * type.
  48  *
  49  * Since: 2.48
  50  */
  51
  52 G_DEFINE_INTERFACE (GDtlsClientConnection, g_dtls_client_connection,
  53                     G_TYPE_DTLS_CONNECTION)
  54
  55 static void
  56 g_dtls_client_connection_default_init (GDtlsClientConnectionInterface *iface)
  57 {
  58   /**
  59    * GDtlsClientConnection:validation-flags:
  60    *
  61    * What steps to perform when validating a certificate received from
  62    * a server. Server certificates that fail to validate in all of the
  63    * ways indicated here will be rejected unless the application
  64    * overrides the default via #GDtlsConnection::accept-certificate.
  65    *
  66    * Since: 2.48
  67    */
  68   g_object_interface_install_property (iface,
  69                                        g_param_spec_flags ("validation-flags",
  70                                                            P_("Validation flags"),
  71                                                            P_("What certificate validation to perform"),
  72                                                            G_TYPE_TLS_CERTIFICATE_FLAGS,
  73                                                            G_TLS_CERTIFICATE_VALIDATE_ALL,
  74                                                            G_PARAM_READWRITE |
  75                                                            G_PARAM_CONSTRUCT |
  76                                                            G_PARAM_STATIC_STRINGS));
  77
  78   /**
  79    * GDtlsClientConnection:server-identity:
  80    *
  81    * A #GSocketConnectable describing the identity of the server that
  82    * is expected on the other end of the connection.
  83    *
  84    * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
  85    * #GDtlsClientConnection:validation-flags, this object will be used
  86    * to determine the expected identify of the remote end of the
  87    * connection; if #GDtlsClientConnection:server-identity is not set,
  88    * or does not match the identity presented by the server, then the
  89    * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
  90    *
  91    * In addition to its use in verifying the server certificate,
  92    * this is also used to give a hint to the server about what
  93    * certificate we expect, which is useful for servers that serve
  94    * virtual hosts.
  95    *
  96    * Since: 2.48
  97    */
  98   g_object_interface_install_property (iface,
  99                                        g_param_spec_object ("server-identity",
 100                                                             P_("Server identity"),
 101                                                             P_("GSocketConnectable identifying the server"),
 102                                                             G_TYPE_SOCKET_CONNECTABLE,
 103                                                             G_PARAM_READWRITE |
 104                                                             G_PARAM_CONSTRUCT |
 105                                                             G_PARAM_STATIC_STRINGS));
 106
 107   /**
 108    * GDtlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
 109    *
 110    * A list of the distinguished names of the Certificate Authorities
 111    * that the server will accept client certificates signed by. If the
 112    * server requests a client certificate during the handshake, then
 113    * this property will be set after the handshake completes.
 114    *
 115    * Each item in the list is a #GByteArray which contains the complete
 116    * subject DN of the certificate authority.
 117    *
 118    * Since: 2.48
 119    */
 120   g_object_interface_install_property (iface,
 121                                        g_param_spec_pointer ("accepted-cas",
 122                                                              P_("Accepted CAs"),
 123                                                              P_("Distinguished names of the CAs the server accepts certificates from"),
 124                                                              G_PARAM_READABLE |
 125                                                              G_PARAM_STATIC_STRINGS));
 126 }
 127
 128 /**
 129  * g_dtls_client_connection_new:
 130  * @base_socket: the #GDatagramBased to wrap
 131  * @server_identity: (nullable): the expected identity of the server
 132  * @error: #GError for error reporting, or %NULL to ignore.
 133  *
 134  * Creates a new #GDtlsClientConnection wrapping @base_socket which is
 135  * assumed to communicate with the server identified by @server_identity.
 136  *
 137  * Returns: (transfer full) (type GDtlsClientConnection): the new
 138  *   #GDtlsClientConnection, or %NULL on error
 139  *
 140  * Since: 2.48
 141  */
 142 GDatagramBased *
 143 g_dtls_client_connection_new (GDatagramBased      *base_socket,
 144                               GSocketConnectable  *server_identity,
 145                               GError             **error)
 146 {
 147   GObject *conn;
 148   GTlsBackend *backend;
 149
 150   backend = g_tls_backend_get_default ();
 151   conn = g_initable_new (g_tls_backend_get_dtls_client_connection_type (backend),
 152                          NULL, error,
 153                          "base-socket", base_socket,
 154                          "server-identity", server_identity,
 155                          NULL);
 156   return G_DATAGRAM_BASED (conn);
 157 }
 158
 159 /**
 160  * g_dtls_client_connection_get_validation_flags:
 161  * @conn: the #GDtlsClientConnection
 162  *
 163  * Gets @conn's validation flags
 164  *
 165  * Returns: the validation flags
 166  *
 167  * Since: 2.48
 168  */
 169 GTlsCertificateFlags
 170 g_dtls_client_connection_get_validation_flags (GDtlsClientConnection *conn)
 171 {
 172   GTlsCertificateFlags flags = 0;
 173
 174   g_return_val_if_fail (G_IS_DTLS_CLIENT_CONNECTION (conn), 0);
 175
 176   g_object_get (G_OBJECT (conn), "validation-flags", &flags, NULL);
 177   return flags;
 178 }
 179
 180 /**
 181  * g_dtls_client_connection_set_validation_flags:
 182  * @conn: the #GDtlsClientConnection
 183  * @flags: the #GTlsCertificateFlags to use
 184  *
 185  * Sets @conn's validation flags, to override the default set of
 186  * checks performed when validating a server certificate. By default,
 187  * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
 188  *
 189  * Since: 2.48
 190  */
 191 void
 192 g_dtls_client_connection_set_validation_flags (GDtlsClientConnection  *conn,
 193                                                GTlsCertificateFlags   flags)
 194 {
 195   g_return_if_fail (G_IS_DTLS_CLIENT_CONNECTION (conn));
 196
 197   g_object_set (G_OBJECT (conn), "validation-flags", flags, NULL);
 198 }
 199
 200 /**
 201  * g_dtls_client_connection_get_server_identity:
 202  * @conn: the #GDtlsClientConnection
 203  *
 204  * Gets @conn's expected server identity
 205  *
 206  * Returns: (transfer none): a #GSocketConnectable describing the
 207  * expected server identity, or %NULL if the expected identity is not
 208  * known.
 209  *
 210  * Since: 2.48
 211  */
 212 GSocketConnectable *
 213 g_dtls_client_connection_get_server_identity (GDtlsClientConnection *conn)
 214 {
 215   GSocketConnectable *identity = NULL;
 216
 217   g_return_val_if_fail (G_IS_DTLS_CLIENT_CONNECTION (conn), 0);
 218
 219   g_object_get (G_OBJECT (conn), "server-identity", &identity, NULL);
 220   if (identity)
 221     g_object_unref (identity);
 222   return identity;
 223 }
 224
 225 /**
 226  * g_dtls_client_connection_set_server_identity:
 227  * @conn: the #GDtlsClientConnection
 228  * @identity: a #GSocketConnectable describing the expected server identity
 229  *
 230  * Sets @conn's expected server identity, which is used both to tell
 231  * servers on virtual hosts which certificate to present, and also
 232  * to let @conn know what name to look for in the certificate when
 233  * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
 234  *
 235  * Since: 2.48
 236  */
 237 void
 238 g_dtls_client_connection_set_server_identity (GDtlsClientConnection *conn,
 239                                               GSocketConnectable    *identity)
 240 {
 241   g_return_if_fail (G_IS_DTLS_CLIENT_CONNECTION (conn));
 242
 243   g_object_set (G_OBJECT (conn), "server-identity", identity, NULL);
 244 }
 245
 246 /**
 247  * g_dtls_client_connection_get_accepted_cas:
 248  * @conn: the #GDtlsClientConnection
 249  *
 250  * Gets the list of distinguished names of the Certificate Authorities
 251  * that the server will accept certificates from. This will be set
 252  * during the TLS handshake if the server requests a certificate.
 253  * Otherwise, it will be %NULL.
 254  *
 255  * Each item in the list is a #GByteArray which contains the complete
 256  * subject DN of the certificate authority.
 257  *
 258  * Returns: (element-type GByteArray) (transfer full): the list of
 259  * CA DNs. You should unref each element with g_byte_array_unref() and then
 260  * the free the list with g_list_free().
 261  *
 262  * Since: 2.48
 263  */
 264 GList *
 265 g_dtls_client_connection_get_accepted_cas (GDtlsClientConnection *conn)
 266 {
 267   GList *accepted_cas = NULL;
 268
 269   g_return_val_if_fail (G_IS_DTLS_CLIENT_CONNECTION (conn), NULL);
 270
 271   g_object_get (G_OBJECT (conn), "accepted-cas", &accepted_cas, NULL);
 272   return accepted_cas;
 273 }