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