gio/gdtlsconnection.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 "gdtlsconnection.h"
  24 #include "gcancellable.h"
  25 #include "gioenumtypes.h"
  26 #include "gsocket.h"
  27 #include "gtlsbackend.h"
  28 #include "gtlscertificate.h"
  29 #include "gtlsconnection.h"
  30 #include "gdtlsclientconnection.h"
  31 #include "gtlsdatabase.h"
  32 #include "gtlsinteraction.h"
  33 #include "glibintl.h"
  34 #include "gmarshal-internal.h"
  35
  36 /**
  37  * SECTION:gdtlsconnection
  38  * @short_description: DTLS connection type
  39  * @include: gio/gio.h
  40  *
  41  * #GDtlsConnection is the base DTLS connection class type, which wraps
  42  * a #GDatagramBased and provides DTLS encryption on top of it. Its
  43  * subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
  44  * implement client-side and server-side DTLS, respectively.
  45  *
  46  * For TLS support, see #GTlsConnection.
  47  *
  48  * As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
  49  * presenting a datagram-socket-like API for the encrypted connection. This
  50  * operates over a base datagram connection, which is also a #GDatagramBased
  51  * (#GDtlsConnection:base-socket).
  52  *
  53  * To close a DTLS connection, use g_dtls_connection_close().
  54  *
  55  * Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
  56  * on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
  57  * do that if they wish. If they do not, and g_socket_close() is called on the
  58  * base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
  59  * error on further I/O.
  60  *
  61  * Since: 2.48
  62  */
  63
  64 /**
  65  * GDtlsConnection:
  66  *
  67  * Abstract base class for the backend-specific #GDtlsClientConnection
  68  * and #GDtlsServerConnection types.
  69  *
  70  * Since: 2.48
  71  */
  72
  73 G_DEFINE_INTERFACE (GDtlsConnection, g_dtls_connection, G_TYPE_DATAGRAM_BASED)
  74
  75 enum {
  76   ACCEPT_CERTIFICATE,
  77   LAST_SIGNAL
  78 };
  79
  80 static guint signals[LAST_SIGNAL] = { 0 };
  81
  82 enum {
  83   PROP_BASE_SOCKET = 1,
  84   PROP_REQUIRE_CLOSE_NOTIFY,
  85   PROP_REHANDSHAKE_MODE,
  86   PROP_DATABASE,
  87   PROP_INTERACTION,
  88   PROP_CERTIFICATE,
  89   PROP_PEER_CERTIFICATE,
  90   PROP_PEER_CERTIFICATE_ERRORS,
  91 };
  92
  93 static void
  94 g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
  95 {
  96   /**
  97    * GDtlsConnection:base-socket:
  98    *
  99    * The #GDatagramBased that the connection wraps. Note that this may be any
 100    * implementation of #GDatagramBased, not just a #GSocket.
 101    *
 102    * Since: 2.48
 103    */
 104   g_object_interface_install_property (iface,
 105                                        g_param_spec_object ("base-socket",
 106                                                             P_("Base Socket"),
 107                                                             P_("The GDatagramBased that the connection wraps"),
 108                                                             G_TYPE_DATAGRAM_BASED,
 109                                                             G_PARAM_READWRITE |
 110                                                             G_PARAM_CONSTRUCT_ONLY |
 111                                                             G_PARAM_STATIC_STRINGS));
 112   /**
 113    * GDtlsConnection:database: (nullable)
 114    *
 115    * The certificate database to use when verifying this TLS connection.
 116    * If no certificate database is set, then the default database will be
 117    * used. See g_tls_backend_get_default_database().
 118    *
 119    * Since: 2.48
 120    */
 121   g_object_interface_install_property (iface,
 122                                        g_param_spec_object ("database",
 123                                                             P_("Database"),
 124                                                             P_("Certificate database to use for looking up or verifying certificates"),
 125                                                             G_TYPE_TLS_DATABASE,
 126                                                             G_PARAM_READWRITE |
 127                                                             G_PARAM_STATIC_STRINGS));
 128   /**
 129    * GDtlsConnection:interaction: (nullable)
 130    *
 131    * A #GTlsInteraction object to be used when the connection or certificate
 132    * database need to interact with the user. This will be used to prompt the
 133    * user for passwords where necessary.
 134    *
 135    * Since: 2.48
 136    */
 137   g_object_interface_install_property (iface,
 138                                        g_param_spec_object ("interaction",
 139                                                             P_("Interaction"),
 140                                                             P_("Optional object for user interaction"),
 141                                                             G_TYPE_TLS_INTERACTION,
 142                                                             G_PARAM_READWRITE |
 143                                                             G_PARAM_STATIC_STRINGS));
 144   /**
 145    * GDtlsConnection:require-close-notify:
 146    *
 147    * Whether or not proper TLS close notification is required.
 148    * See g_dtls_connection_set_require_close_notify().
 149    *
 150    * Since: 2.48
 151    */
 152   g_object_interface_install_property (iface,
 153                                        g_param_spec_boolean ("require-close-notify",
 154                                                              P_("Require close notify"),
 155                                                              P_("Whether to require proper TLS close notification"),
 156                                                              TRUE,
 157                                                              G_PARAM_READWRITE |
 158                                                              G_PARAM_CONSTRUCT |
 159                                                              G_PARAM_STATIC_STRINGS));
 160   /**
 161    * GDtlsConnection:rehandshake-mode:
 162    *
 163    * The rehandshaking mode. See
 164    * g_dtls_connection_set_rehandshake_mode().
 165    *
 166    * Since: 2.48
 167    *
 168    * Deprecated: 2.60: The rehandshake mode is ignored.
 169    */
 170   g_object_interface_install_property (iface,
 171                                        g_param_spec_enum ("rehandshake-mode",
 172                                                           P_("Rehandshake mode"),
 173                                                           P_("When to allow rehandshaking"),
 174                                                           G_TYPE_TLS_REHANDSHAKE_MODE,
 175                                                           G_TLS_REHANDSHAKE_NEVER,
 176                                                           G_PARAM_READWRITE |
 177                                                           G_PARAM_CONSTRUCT |
 178                                                           G_PARAM_STATIC_STRINGS |
 179                                                           G_PARAM_DEPRECATED));
 180   /**
 181    * GDtlsConnection:certificate:
 182    *
 183    * The connection's certificate; see
 184    * g_dtls_connection_set_certificate().
 185    *
 186    * Since: 2.48
 187    */
 188   g_object_interface_install_property (iface,
 189                                        g_param_spec_object ("certificate",
 190                                                             P_("Certificate"),
 191                                                             P_("The connection’s certificate"),
 192                                                             G_TYPE_TLS_CERTIFICATE,
 193                                                             G_PARAM_READWRITE |
 194                                                             G_PARAM_STATIC_STRINGS));
 195   /**
 196    * GDtlsConnection:peer-certificate: (nullable)
 197    *
 198    * The connection's peer's certificate, after the TLS handshake has
 199    * completed or failed. Note in particular that this is not yet set
 200    * during the emission of #GDtlsConnection::accept-certificate.
 201    *
 202    * (You can watch for a #GObject::notify signal on this property to
 203    * detect when a handshake has occurred.)
 204    *
 205    * Since: 2.48
 206    */
 207   g_object_interface_install_property (iface,
 208                                        g_param_spec_object ("peer-certificate",
 209                                                             P_("Peer Certificate"),
 210                                                             P_("The connection’s peer’s certificate"),
 211                                                             G_TYPE_TLS_CERTIFICATE,
 212                                                             G_PARAM_READABLE |
 213                                                             G_PARAM_STATIC_STRINGS));
 214   /**
 215    * GDtlsConnection:peer-certificate-errors:
 216    *
 217    * The errors noticed while verifying
 218    * #GDtlsConnection:peer-certificate. Normally this should be 0, but
 219    * it may not be if #GDtlsClientConnection:validation-flags is not
 220    * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
 221    * #GDtlsConnection::accept-certificate overrode the default
 222    * behavior.
 223    *
 224    * Since: 2.48
 225    */
 226   g_object_interface_install_property (iface,
 227                                        g_param_spec_flags ("peer-certificate-errors",
 228                                                            P_("Peer Certificate Errors"),
 229                                                            P_("Errors found with the peer’s certificate"),
 230                                                            G_TYPE_TLS_CERTIFICATE_FLAGS,
 231                                                            0,
 232                                                            G_PARAM_READABLE |
 233                                                            G_PARAM_STATIC_STRINGS));
 234   /**
 235    * GDtlsConnection:advertised-protocols: (nullable)
 236    *
 237    * The list of application-layer protocols that the connection
 238    * advertises that it is willing to speak. See
 239    * g_dtls_connection_set_advertised_protocols().
 240    *
 241    * Since: 2.60
 242    */
 243   g_object_interface_install_property (iface,
 244                                        g_param_spec_boxed ("advertised-protocols",
 245                                                            P_("Advertised Protocols"),
 246                                                            P_("Application-layer protocols available on this connection"),
 247                                                            G_TYPE_STRV,
 248                                                            G_PARAM_READWRITE |
 249                                                            G_PARAM_STATIC_STRINGS));
 250   /**
 251    * GDtlsConnection:negotiated-protocol:
 252    *
 253    * The application-layer protocol negotiated during the TLS
 254    * handshake. See g_dtls_connection_get_negotiated_protocol().
 255    *
 256    * Since: 2.60
 257    */
 258   g_object_interface_install_property (iface,
 259                                        g_param_spec_string ("negotiated-protocol",
 260                                                             P_("Negotiated Protocol"),
 261                                                             P_("Application-layer protocol negotiated for this connection"),
 262                                                             NULL,
 263                                                             G_PARAM_READABLE |
 264                                                             G_PARAM_STATIC_STRINGS));
 265
 266   /**
 267    * GDtlsConnection::accept-certificate:
 268    * @conn: a #GDtlsConnection
 269    * @peer_cert: the peer's #GTlsCertificate
 270    * @errors: the problems with @peer_cert.
 271    *
 272    * Emitted during the TLS handshake after the peer certificate has
 273    * been received. You can examine @peer_cert's certification path by
 274    * calling g_tls_certificate_get_issuer() on it.
 275    *
 276    * For a client-side connection, @peer_cert is the server's
 277    * certificate, and the signal will only be emitted if the
 278    * certificate was not acceptable according to @conn's
 279    * #GDtlsClientConnection:validation_flags. If you would like the
 280    * certificate to be accepted despite @errors, return %TRUE from the
 281    * signal handler. Otherwise, if no handler accepts the certificate,
 282    * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
 283    *
 284    * For a server-side connection, @peer_cert is the certificate
 285    * presented by the client, if this was requested via the server's
 286    * #GDtlsServerConnection:authentication_mode. On the server side,
 287    * the signal is always emitted when the client presents a
 288    * certificate, and the certificate will only be accepted if a
 289    * handler returns %TRUE.
 290    *
 291    * Note that if this signal is emitted as part of asynchronous I/O
 292    * in the main thread, then you should not attempt to interact with
 293    * the user before returning from the signal handler. If you want to
 294    * let the user decide whether or not to accept the certificate, you
 295    * would have to return %FALSE from the signal handler on the first
 296    * attempt, and then after the connection attempt returns a
 297    * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
 298    * if the user decides to accept the certificate, remember that fact,
 299    * create a new connection, and return %TRUE from the signal handler
 300    * the next time.
 301    *
 302    * If you are doing I/O in another thread, you do not
 303    * need to worry about this, and can simply block in the signal
 304    * handler until the UI thread returns an answer.
 305    *
 306    * Returns: %TRUE to accept @peer_cert (which will also
 307    * immediately end the signal emission). %FALSE to allow the signal
 308    * emission to continue, which will cause the handshake to fail if
 309    * no one else overrides it.
 310    *
 311    * Since: 2.48
 312    */
 313   signals[ACCEPT_CERTIFICATE] =
 314     g_signal_new (I_("accept-certificate"),
 315                   G_TYPE_DTLS_CONNECTION,
 316                   G_SIGNAL_RUN_LAST,
 317                   G_STRUCT_OFFSET (GDtlsConnectionInterface, accept_certificate),
 318                   g_signal_accumulator_true_handled, NULL,
 319                   _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGS,
 320                   G_TYPE_BOOLEAN, 2,
 321                   G_TYPE_TLS_CERTIFICATE,
 322                   G_TYPE_TLS_CERTIFICATE_FLAGS);
 323   g_signal_set_va_marshaller (signals[ACCEPT_CERTIFICATE],
 324                               G_TYPE_FROM_INTERFACE (iface),
 325                               _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGSv);
 326 }
 327
 328 /**
 329  * g_dtls_connection_set_database:
 330  * @conn: a #GDtlsConnection
 331  * @database: (nullable): a #GTlsDatabase
 332  *
 333  * Sets the certificate database that is used to verify peer certificates.
 334  * This is set to the default database by default. See
 335  * g_tls_backend_get_default_database(). If set to %NULL, then
 336  * peer certificate validation will always set the
 337  * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
 338  * #GDtlsConnection::accept-certificate will always be emitted on
 339  * client-side connections, unless that bit is not set in
 340  * #GDtlsClientConnection:validation-flags).
 341  *
 342  * Since: 2.48
 343  */
 344 void
 345 g_dtls_connection_set_database (GDtlsConnection *conn,
 346                                 GTlsDatabase    *database)
 347 {
 348   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 349   g_return_if_fail (database == NULL || G_IS_TLS_DATABASE (database));
 350
 351   g_object_set (G_OBJECT (conn),
 352                 "database", database,
 353                 NULL);
 354 }
 355
 356 /**
 357  * g_dtls_connection_get_database:
 358  * @conn: a #GDtlsConnection
 359  *
 360  * Gets the certificate database that @conn uses to verify
 361  * peer certificates. See g_dtls_connection_set_database().
 362  *
 363  * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL
 364  *
 365  * Since: 2.48
 366  */
 367 GTlsDatabase*
 368 g_dtls_connection_get_database (GDtlsConnection *conn)
 369 {
 370   GTlsDatabase *database = NULL;
 371
 372   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
 373
 374   g_object_get (G_OBJECT (conn),
 375                 "database", &database,
 376                 NULL);
 377   if (database)
 378     g_object_unref (database);
 379   return database;
 380 }
 381
 382 /**
 383  * g_dtls_connection_set_certificate:
 384  * @conn: a #GDtlsConnection
 385  * @certificate: the certificate to use for @conn
 386  *
 387  * This sets the certificate that @conn will present to its peer
 388  * during the TLS handshake. For a #GDtlsServerConnection, it is
 389  * mandatory to set this, and that will normally be done at construct
 390  * time.
 391  *
 392  * For a #GDtlsClientConnection, this is optional. If a handshake fails
 393  * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
 394  * requires a certificate, and if you try connecting again, you should
 395  * call this method first. You can call
 396  * g_dtls_client_connection_get_accepted_cas() on the failed connection
 397  * to get a list of Certificate Authorities that the server will
 398  * accept certificates from.
 399  *
 400  * (It is also possible that a server will allow the connection with
 401  * or without a certificate; in that case, if you don't provide a
 402  * certificate, you can tell that the server requested one by the fact
 403  * that g_dtls_client_connection_get_accepted_cas() will return
 404  * non-%NULL.)
 405  *
 406  * Since: 2.48
 407  */
 408 void
 409 g_dtls_connection_set_certificate (GDtlsConnection *conn,
 410                                    GTlsCertificate *certificate)
 411 {
 412   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 413   g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
 414
 415   g_object_set (G_OBJECT (conn), "certificate", certificate, NULL);
 416 }
 417
 418 /**
 419  * g_dtls_connection_get_certificate:
 420  * @conn: a #GDtlsConnection
 421  *
 422  * Gets @conn's certificate, as set by
 423  * g_dtls_connection_set_certificate().
 424  *
 425  * Returns: (transfer none) (nullable): @conn's certificate, or %NULL
 426  *
 427  * Since: 2.48
 428  */
 429 GTlsCertificate *
 430 g_dtls_connection_get_certificate (GDtlsConnection *conn)
 431 {
 432   GTlsCertificate *certificate;
 433
 434   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
 435
 436   g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
 437   if (certificate)
 438     g_object_unref (certificate);
 439
 440   return certificate;
 441 }
 442
 443 /**
 444  * g_dtls_connection_set_interaction:
 445  * @conn: a connection
 446  * @interaction: (nullable): an interaction object, or %NULL
 447  *
 448  * Set the object that will be used to interact with the user. It will be used
 449  * for things like prompting the user for passwords.
 450  *
 451  * The @interaction argument will normally be a derived subclass of
 452  * #GTlsInteraction. %NULL can also be provided if no user interaction
 453  * should occur for this connection.
 454  *
 455  * Since: 2.48
 456  */
 457 void
 458 g_dtls_connection_set_interaction (GDtlsConnection *conn,
 459                                    GTlsInteraction *interaction)
 460 {
 461   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 462   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
 463
 464   g_object_set (G_OBJECT (conn), "interaction", interaction, NULL);
 465 }
 466
 467 /**
 468  * g_dtls_connection_get_interaction:
 469  * @conn: a connection
 470  *
 471  * Get the object that will be used to interact with the user. It will be used
 472  * for things like prompting the user for passwords. If %NULL is returned, then
 473  * no user interaction will occur for this connection.
 474  *
 475  * Returns: (transfer none) (nullable): The interaction object.
 476  *
 477  * Since: 2.48
 478  */
 479 GTlsInteraction *
 480 g_dtls_connection_get_interaction (GDtlsConnection       *conn)
 481 {
 482   GTlsInteraction *interaction = NULL;
 483
 484   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
 485
 486   g_object_get (G_OBJECT (conn), "interaction", &interaction, NULL);
 487   if (interaction)
 488     g_object_unref (interaction);
 489
 490   return interaction;
 491 }
 492
 493 /**
 494  * g_dtls_connection_get_peer_certificate:
 495  * @conn: a #GDtlsConnection
 496  *
 497  * Gets @conn's peer's certificate after the handshake has completed
 498  * or failed. (It is not set during the emission of
 499  * #GDtlsConnection::accept-certificate.)
 500  *
 501  * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
 502  *
 503  * Since: 2.48
 504  */
 505 GTlsCertificate *
 506 g_dtls_connection_get_peer_certificate (GDtlsConnection *conn)
 507 {
 508   GTlsCertificate *peer_certificate;
 509
 510   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
 511
 512   g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
 513   if (peer_certificate)
 514     g_object_unref (peer_certificate);
 515
 516   return peer_certificate;
 517 }
 518
 519 /**
 520  * g_dtls_connection_get_peer_certificate_errors:
 521  * @conn: a #GDtlsConnection
 522  *
 523  * Gets the errors associated with validating @conn's peer's
 524  * certificate, after the handshake has completed or failed. (It is
 525  * not set during the emission of #GDtlsConnection::accept-certificate.)
 526  *
 527  * Returns: @conn's peer's certificate errors
 528  *
 529  * Since: 2.48
 530  */
 531 GTlsCertificateFlags
 532 g_dtls_connection_get_peer_certificate_errors (GDtlsConnection *conn)
 533 {
 534   GTlsCertificateFlags errors;
 535
 536   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), 0);
 537
 538   g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
 539   return errors;
 540 }
 541
 542 /**
 543  * g_dtls_connection_set_require_close_notify:
 544  * @conn: a #GDtlsConnection
 545  * @require_close_notify: whether or not to require close notification
 546  *
 547  * Sets whether or not @conn expects a proper TLS close notification
 548  * before the connection is closed. If this is %TRUE (the default),
 549  * then @conn will expect to receive a TLS close notification from its
 550  * peer before the connection is closed, and will return a
 551  * %G_TLS_ERROR_EOF error if the connection is closed without proper
 552  * notification (since this may indicate a network error, or
 553  * man-in-the-middle attack).
 554  *
 555  * In some protocols, the application will know whether or not the
 556  * connection was closed cleanly based on application-level data
 557  * (because the application-level data includes a length field, or is
 558  * somehow self-delimiting); in this case, the close notify is
 559  * redundant and may be omitted. You
 560  * can use g_dtls_connection_set_require_close_notify() to tell @conn
 561  * to allow an "unannounced" connection close, in which case the close
 562  * will show up as a 0-length read, as in a non-TLS
 563  * #GDatagramBased, and it is up to the application to check that
 564  * the data has been fully received.
 565  *
 566  * Note that this only affects the behavior when the peer closes the
 567  * connection; when the application calls g_dtls_connection_close_async() on
 568  * @conn itself, this will send a close notification regardless of the
 569  * setting of this property. If you explicitly want to do an unclean
 570  * close, you can close @conn's #GDtlsConnection:base-socket rather
 571  * than closing @conn itself.
 572  *
 573  * Since: 2.48
 574  */
 575 void
 576 g_dtls_connection_set_require_close_notify (GDtlsConnection *conn,
 577                                             gboolean         require_close_notify)
 578 {
 579   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 580
 581   g_object_set (G_OBJECT (conn),
 582                 "require-close-notify", require_close_notify,
 583                 NULL);
 584 }
 585
 586 /**
 587  * g_dtls_connection_get_require_close_notify:
 588  * @conn: a #GDtlsConnection
 589  *
 590  * Tests whether or not @conn expects a proper TLS close notification
 591  * when the connection is closed. See
 592  * g_dtls_connection_set_require_close_notify() for details.
 593  *
 594  * Returns: %TRUE if @conn requires a proper TLS close notification.
 595  *
 596  * Since: 2.48
 597  */
 598 gboolean
 599 g_dtls_connection_get_require_close_notify (GDtlsConnection *conn)
 600 {
 601   gboolean require_close_notify;
 602
 603   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), TRUE);
 604
 605   g_object_get (G_OBJECT (conn),
 606                 "require-close-notify", &require_close_notify,
 607                 NULL);
 608   return require_close_notify;
 609 }
 610
 611 /**
 612  * g_dtls_connection_set_rehandshake_mode:
 613  * @conn: a #GDtlsConnection
 614  * @mode: the rehandshaking mode
 615  *
 616  * Since GLib 2.64, changing the rehandshake mode is no longer supported
 617  * and will have no effect. With TLS 1.3, rehandshaking has been removed from
 618  * the TLS protocol, replaced by separate post-handshake authentication and
 619  * rekey operations.
 620  *
 621  * Since: 2.48
 622  *
 623  * Deprecated: 2.60. Changing the rehandshake mode is no longer
 624  *   required for compatibility. Also, rehandshaking has been removed
 625  *   from the TLS protocol in TLS 1.3.
 626  */
 627 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 628 void
 629 g_dtls_connection_set_rehandshake_mode (GDtlsConnection     *conn,
 630                                         GTlsRehandshakeMode  mode)
 631 {
 632   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 633
 634   g_object_set (G_OBJECT (conn),
 635                 "rehandshake-mode", G_TLS_REHANDSHAKE_SAFELY,
 636                 NULL);
 637 }
 638 G_GNUC_END_IGNORE_DEPRECATIONS
 639
 640 /**
 641  * g_dtls_connection_get_rehandshake_mode:
 642  * @conn: a #GDtlsConnection
 643  *
 644  * Gets @conn rehandshaking mode. See
 645  * g_dtls_connection_set_rehandshake_mode() for details.
 646  *
 647  * Returns: %G_TLS_REHANDSHAKE_SAFELY
 648  *
 649  * Since: 2.48
 650  *
 651  * Deprecated: 2.64. Changing the rehandshake mode is no longer
 652  *   required for compatibility. Also, rehandshaking has been removed
 653  *   from the TLS protocol in TLS 1.3.
 654  */
 655 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 656 GTlsRehandshakeMode
 657 g_dtls_connection_get_rehandshake_mode (GDtlsConnection *conn)
 658 {
 659   GTlsRehandshakeMode mode;
 660
 661   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), G_TLS_REHANDSHAKE_SAFELY);
 662
 663   /* Continue to call g_object_get(), even though the return value is
 664    * ignored, so that behavior doesn’t change for derived classes.
 665    */
 666   g_object_get (G_OBJECT (conn),
 667                 "rehandshake-mode", &mode,
 668                 NULL);
 669   return G_TLS_REHANDSHAKE_SAFELY;
 670 }
 671 G_GNUC_END_IGNORE_DEPRECATIONS
 672
 673 /**
 674  * g_dtls_connection_handshake:
 675  * @conn: a #GDtlsConnection
 676  * @cancellable: (nullable): a #GCancellable, or %NULL
 677  * @error: a #GError, or %NULL
 678  *
 679  * Attempts a TLS handshake on @conn.
 680  *
 681  * On the client side, it is never necessary to call this method;
 682  * although the connection needs to perform a handshake after
 683  * connecting, #GDtlsConnection will handle this for you automatically
 684  * when you try to send or receive data on the connection. You can call
 685  * g_dtls_connection_handshake() manually if you want to know whether
 686  * the initial handshake succeeded or failed (as opposed to just
 687  * immediately trying to use @conn to read or write, in which case,
 688  * if it fails, it may not be possible to tell if it failed before
 689  * or after completing the handshake), but beware that servers may reject
 690  * client authentication after the handshake has completed, so a
 691  * successful handshake does not indicate the connection will be usable.
 692  *
 693  * Likewise, on the server side, although a handshake is necessary at
 694  * the beginning of the communication, you do not need to call this
 695  * function explicitly unless you want clearer error reporting.
 696  *
 697  * Previously, calling g_dtls_connection_handshake() after the initial
 698  * handshake would trigger a rehandshake; however, this usage was
 699  * deprecated in GLib 2.60 because rehandshaking was removed from the
 700  * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
 701  * the initial handshake will no longer do anything.
 702  *
 703  * #GDtlsConnection::accept_certificate may be emitted during the
 704  * handshake.
 705  *
 706  * Returns: success or failure
 707  *
 708  * Since: 2.48
 709  */
 710 gboolean
 711 g_dtls_connection_handshake (GDtlsConnection  *conn,
 712                              GCancellable     *cancellable,
 713                              GError          **error)
 714 {
 715   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
 716
 717   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake (conn, cancellable,
 718                                                             error);
 719 }
 720
 721 /**
 722  * g_dtls_connection_handshake_async:
 723  * @conn: a #GDtlsConnection
 724  * @io_priority: the [I/O priority][io-priority] of the request
 725  * @cancellable: (nullable): a #GCancellable, or %NULL
 726  * @callback: callback to call when the handshake is complete
 727  * @user_data: the data to pass to the callback function
 728  *
 729  * Asynchronously performs a TLS handshake on @conn. See
 730  * g_dtls_connection_handshake() for more information.
 731  *
 732  * Since: 2.48
 733  */
 734 void
 735 g_dtls_connection_handshake_async (GDtlsConnection      *conn,
 736                                    int                   io_priority,
 737                                    GCancellable         *cancellable,
 738                                    GAsyncReadyCallback   callback,
 739                                    gpointer              user_data)
 740 {
 741   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 742
 743   G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake_async (conn, io_priority,
 744                                                            cancellable,
 745                                                            callback, user_data);
 746 }
 747
 748 /**
 749  * g_dtls_connection_handshake_finish:
 750  * @conn: a #GDtlsConnection
 751  * @result: a #GAsyncResult.
 752  * @error: a #GError pointer, or %NULL
 753  *
 754  * Finish an asynchronous TLS handshake operation. See
 755  * g_dtls_connection_handshake() for more information.
 756  *
 757  * Returns: %TRUE on success, %FALSE on failure, in which
 758  * case @error will be set.
 759  *
 760  * Since: 2.48
 761  */
 762 gboolean
 763 g_dtls_connection_handshake_finish (GDtlsConnection  *conn,
 764                                     GAsyncResult     *result,
 765                                     GError          **error)
 766 {
 767   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
 768
 769   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake_finish (conn,
 770                                                                    result,
 771                                                                    error);
 772 }
 773
 774 /**
 775  * g_dtls_connection_shutdown:
 776  * @conn: a #GDtlsConnection
 777  * @shutdown_read: %TRUE to stop reception of incoming datagrams
 778  * @shutdown_write: %TRUE to stop sending outgoing datagrams
 779  * @cancellable: (nullable): a #GCancellable, or %NULL
 780  * @error: a #GError, or %NULL
 781  *
 782  * Shut down part or all of a DTLS connection.
 783  *
 784  * If @shutdown_read is %TRUE then the receiving side of the connection is shut
 785  * down, and further reading is disallowed. Subsequent calls to
 786  * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
 787  *
 788  * If @shutdown_write is %TRUE then the sending side of the connection is shut
 789  * down, and further writing is disallowed. Subsequent calls to
 790  * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
 791  *
 792  * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
 793  * is equivalent to calling g_dtls_connection_close().
 794  *
 795  * If @cancellable is cancelled, the #GDtlsConnection may be left
 796  * partially-closed and any pending untransmitted data may be lost. Call
 797  * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
 798  *
 799  * Returns: %TRUE on success, %FALSE otherwise
 800  *
 801  * Since: 2.48
 802  */
 803 gboolean
 804 g_dtls_connection_shutdown (GDtlsConnection  *conn,
 805                             gboolean          shutdown_read,
 806                             gboolean          shutdown_write,
 807                             GCancellable     *cancellable,
 808                             GError          **error)
 809 {
 810   GDtlsConnectionInterface *iface;
 811
 812   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
 813   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
 814                         FALSE);
 815   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 816
 817   if (!shutdown_read && !shutdown_write)
 818     return TRUE;
 819
 820   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
 821   g_assert (iface->shutdown != NULL);
 822
 823   return iface->shutdown (conn, shutdown_read, shutdown_write,
 824                           cancellable, error);
 825 }
 826
 827 /**
 828  * g_dtls_connection_shutdown_async:
 829  * @conn: a #GDtlsConnection
 830  * @shutdown_read: %TRUE to stop reception of incoming datagrams
 831  * @shutdown_write: %TRUE to stop sending outgoing datagrams
 832  * @io_priority: the [I/O priority][io-priority] of the request
 833  * @cancellable: (nullable): a #GCancellable, or %NULL
 834  * @callback: callback to call when the shutdown operation is complete
 835  * @user_data: the data to pass to the callback function
 836  *
 837  * Asynchronously shut down part or all of the DTLS connection. See
 838  * g_dtls_connection_shutdown() for more information.
 839  *
 840  * Since: 2.48
 841  */
 842 void
 843 g_dtls_connection_shutdown_async (GDtlsConnection      *conn,
 844                                   gboolean              shutdown_read,
 845                                   gboolean              shutdown_write,
 846                                   int                   io_priority,
 847                                   GCancellable         *cancellable,
 848                                   GAsyncReadyCallback   callback,
 849                                   gpointer              user_data)
 850 {
 851   GDtlsConnectionInterface *iface;
 852
 853   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 854   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 855
 856   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
 857   g_assert (iface->shutdown_async != NULL);
 858
 859   iface->shutdown_async (conn, TRUE, TRUE, io_priority, cancellable,
 860                          callback, user_data);
 861 }
 862
 863 /**
 864  * g_dtls_connection_shutdown_finish:
 865  * @conn: a #GDtlsConnection
 866  * @result: a #GAsyncResult
 867  * @error: a #GError pointer, or %NULL
 868  *
 869  * Finish an asynchronous TLS shutdown operation. See
 870  * g_dtls_connection_shutdown() for more information.
 871  *
 872  * Returns: %TRUE on success, %FALSE on failure, in which
 873  * case @error will be set
 874  *
 875  * Since: 2.48
 876  */
 877 gboolean
 878 g_dtls_connection_shutdown_finish (GDtlsConnection  *conn,
 879                                    GAsyncResult     *result,
 880                                    GError          **error)
 881 {
 882   GDtlsConnectionInterface *iface;
 883
 884   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
 885   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 886
 887   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
 888   g_assert (iface->shutdown_finish != NULL);
 889
 890   return iface->shutdown_finish (conn, result, error);
 891 }
 892
 893 /**
 894  * g_dtls_connection_close:
 895  * @conn: a #GDtlsConnection
 896  * @cancellable: (nullable): a #GCancellable, or %NULL
 897  * @error: a #GError, or %NULL
 898  *
 899  * Close the DTLS connection. This is equivalent to calling
 900  * g_dtls_connection_shutdown() to shut down both sides of the connection.
 901  *
 902  * Closing a #GDtlsConnection waits for all buffered but untransmitted data to
 903  * be sent before it completes. It then sends a `close_notify` DTLS alert to the
 904  * peer and may wait for a `close_notify` to be received from the peer. It does
 905  * not close the underlying #GDtlsConnection:base-socket; that must be closed
 906  * separately.
 907  *
 908  * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED.
 909  * Closing a #GDtlsConnection multiple times will not return an error.
 910  *
 911  * #GDtlsConnections will be automatically closed when the last reference is
 912  * dropped, but you might want to call this function to make sure resources are
 913  * released as early as possible.
 914  *
 915  * If @cancellable is cancelled, the #GDtlsConnection may be left
 916  * partially-closed and any pending untransmitted data may be lost. Call
 917  * g_dtls_connection_close() again to complete closing the #GDtlsConnection.
 918  *
 919  * Returns: %TRUE on success, %FALSE otherwise
 920  *
 921  * Since: 2.48
 922  */
 923 gboolean
 924 g_dtls_connection_close (GDtlsConnection  *conn,
 925                          GCancellable     *cancellable,
 926                          GError          **error)
 927 {
 928   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
 929   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
 930                         FALSE);
 931   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 932
 933   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown (conn, TRUE, TRUE,
 934                                                            cancellable, error);
 935 }
 936
 937 /**
 938  * g_dtls_connection_close_async:
 939  * @conn: a #GDtlsConnection
 940  * @io_priority: the [I/O priority][io-priority] of the request
 941  * @cancellable: (nullable): a #GCancellable, or %NULL
 942  * @callback: callback to call when the close operation is complete
 943  * @user_data: the data to pass to the callback function
 944  *
 945  * Asynchronously close the DTLS connection. See g_dtls_connection_close() for
 946  * more information.
 947  *
 948  * Since: 2.48
 949  */
 950 void
 951 g_dtls_connection_close_async (GDtlsConnection      *conn,
 952                                int                   io_priority,
 953                                GCancellable         *cancellable,
 954                                GAsyncReadyCallback   callback,
 955                                gpointer              user_data)
 956 {
 957   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
 958   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 959
 960   G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown_async (conn, TRUE, TRUE,
 961                                                           io_priority,
 962                                                           cancellable,
 963                                                           callback, user_data);
 964 }
 965
 966 /**
 967  * g_dtls_connection_close_finish:
 968  * @conn: a #GDtlsConnection
 969  * @result: a #GAsyncResult
 970  * @error: a #GError pointer, or %NULL
 971  *
 972  * Finish an asynchronous TLS close operation. See g_dtls_connection_close()
 973  * for more information.
 974  *
 975  * Returns: %TRUE on success, %FALSE on failure, in which
 976  * case @error will be set
 977  *
 978  * Since: 2.48
 979  */
 980 gboolean
 981 g_dtls_connection_close_finish (GDtlsConnection  *conn,
 982                                 GAsyncResult     *result,
 983                                 GError          **error)
 984 {
 985   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
 986   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 987
 988   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown_finish (conn, result,
 989                                                                   error);
 990 }
 991
 992 /**
 993  * g_dtls_connection_emit_accept_certificate:
 994  * @conn: a #GDtlsConnection
 995  * @peer_cert: the peer's #GTlsCertificate
 996  * @errors: the problems with @peer_cert
 997  *
 998  * Used by #GDtlsConnection implementations to emit the
 999  * #GDtlsConnection::accept-certificate signal.
1000  *
1001  * Returns: %TRUE if one of the signal handlers has returned
1002  *     %TRUE to accept @peer_cert
1003  *
1004  * Since: 2.48
1005  */
1006 gboolean
1007 g_dtls_connection_emit_accept_certificate (GDtlsConnection      *conn,
1008                                            GTlsCertificate      *peer_cert,
1009                                            GTlsCertificateFlags  errors)
1010 {
1011   gboolean accept = FALSE;
1012
1013   g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
1014                  peer_cert, errors, &accept);
1015   return accept;
1016 }
1017
1018 /**
1019  * g_dtls_connection_set_advertised_protocols:
1020  * @conn: a #GDtlsConnection
1021  * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
1022  *   array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
1023  *
1024  * Sets the list of application-layer protocols to advertise that the
1025  * caller is willing to speak on this connection. The
1026  * Application-Layer Protocol Negotiation (ALPN) extension will be
1027  * used to negotiate a compatible protocol with the peer; use
1028  * g_dtls_connection_get_negotiated_protocol() to find the negotiated
1029  * protocol after the handshake.  Specifying %NULL for the the value
1030  * of @protocols will disable ALPN negotiation.
1031  *
1032  * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
1033  * for a list of registered protocol IDs.
1034  *
1035  * Since: 2.60
1036  */
1037 void
1038 g_dtls_connection_set_advertised_protocols (GDtlsConnection     *conn,
1039                                             const gchar * const *protocols)
1040 {
1041   GDtlsConnectionInterface *iface;
1042
1043   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
1044   if (iface->set_advertised_protocols == NULL)
1045     return;
1046
1047   iface->set_advertised_protocols (conn, protocols);
1048 }
1049
1050 /**
1051  * g_dtls_connection_get_negotiated_protocol:
1052  * @conn: a #GDtlsConnection
1053  *
1054  * Gets the name of the application-layer protocol negotiated during
1055  * the handshake.
1056  *
1057  * If the peer did not use the ALPN extension, or did not advertise a
1058  * protocol that matched one of @conn's protocols, or the TLS backend
1059  * does not support ALPN, then this will be %NULL. See
1060  * g_dtls_connection_set_advertised_protocols().
1061  *
1062  * Returns: (nullable): the negotiated protocol, or %NULL
1063  *
1064  * Since: 2.60
1065  */
1066 const gchar *
1067 g_dtls_connection_get_negotiated_protocol (GDtlsConnection *conn)
1068 {
1069   GDtlsConnectionInterface *iface;
1070
1071   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
1072   if (iface->set_advertised_protocols == NULL)
1073     return NULL;
1074
1075   return iface->get_negotiated_protocol (conn);
1076 }
1077
1078 /**
1079  * g_dtls_connection_get_channel_binding_data:
1080  * @conn: a #GDtlsConnection
1081  * @type: #GTlsChannelBindingType type of data to fetch
1082  * @data: (out callee-allocates)(optional)(transfer none): #GByteArray is
1083  *        filled with the binding data, or %NULL
1084  * @error: a #GError pointer, or %NULL
1085  *
1086  * Query the TLS backend for TLS channel binding data of @type for @conn.
1087  *
1088  * This call retrieves TLS channel binding data as specified in RFC
1089  * [5056](https://tools.ietf.org/html/rfc5056), RFC
1090  * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs.  The
1091  * binding data is returned in @data.  The @data is resized by the callee
1092  * using #GByteArray buffer management and will be freed when the @data
1093  * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only
1094  * check whether TLS backend is able to fetch the data (e.g. whether @type
1095  * is supported by the TLS backend). It does not guarantee that the data
1096  * will be available though.  That could happen if TLS connection does not
1097  * support @type or the binding data is not available yet due to additional
1098  * negotiation or input required.
1099  *
1100  * Returns: %TRUE on success, %FALSE otherwise
1101  *
1102  * Since: 2.66
1103  */
1104 gboolean
1105 g_dtls_connection_get_channel_binding_data (GDtlsConnection         *conn,
1106                                             GTlsChannelBindingType   type,
1107                                             GByteArray              *data,
1108                                             GError                 **error)
1109 {
1110   GDtlsConnectionInterface *iface;
1111
1112   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
1113   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1114
1115   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
1116   if (iface->get_binding_data == NULL)
1117     {
1118       g_set_error_literal (error, G_TLS_CHANNEL_BINDING_ERROR,
1119           G_TLS_CHANNEL_BINDING_ERROR_NOT_IMPLEMENTED,
1120           _("TLS backend does not implement TLS binding retrieval"));
1121       return FALSE;
1122     }
1123
1124   return iface->get_binding_data (conn, type, data, error);
1125 }