gio/gtlsconnection.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2010 Red Hat, Inc
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "config.h"
  22 #include "glib.h"
  23
  24 #include "gtlsconnection.h"
  25 #include "gcancellable.h"
  26 #include "gioenumtypes.h"
  27 #include "gsocket.h"
  28 #include "gtlsbackend.h"
  29 #include "gtlscertificate.h"
  30 #include "gtlsclientconnection.h"
  31 #include "glibintl.h"
  32
  33 /**
  34  * SECTION:gtlsconnection
  35  * @short_description: TLS connection type
  36  * @include: gio/gio.h
  37  *
  38  * #GTlsConnection is the base TLS connection class type, which wraps
  39  * a #GIOStream and provides TLS encryption on top of it. Its
  40  * subclasses, #GTlsClientConnection and #GTlsServerConnection,
  41  * implement client-side and server-side TLS, respectively.
  42  *
  43  * Since: 2.28
  44  */
  45
  46 /**
  47  * GTlsConnection:
  48  *
  49  * Abstract base class for the backend-specific #GTlsClientConnection
  50  * and #GTlsServerConnection types.
  51  *
  52  * Since: 2.28
  53  */
  54
  55 G_DEFINE_ABSTRACT_TYPE (GTlsConnection, g_tls_connection, G_TYPE_IO_STREAM)
  56
  57 static void g_tls_connection_get_property (GObject    *object,
  58                                            guint       prop_id,
  59                                            GValue     *value,
  60                                            GParamSpec *pspec);
  61 static void g_tls_connection_set_property (GObject      *object,
  62                                            guint         prop_id,
  63                                            const GValue *value,
  64                                            GParamSpec   *pspec);
  65
  66 enum {
  67   ACCEPT_CERTIFICATE,
  68
  69   LAST_SIGNAL
  70 };
  71
  72 static guint signals[LAST_SIGNAL] = { 0 };
  73
  74 enum {
  75   PROP_0,
  76   PROP_BASE_IO_STREAM,
  77   PROP_REQUIRE_CLOSE_NOTIFY,
  78   PROP_REHANDSHAKE_MODE,
  79   PROP_USE_SYSTEM_CERTDB,
  80   PROP_CERTIFICATE,
  81   PROP_PEER_CERTIFICATE,
  82   PROP_PEER_CERTIFICATE_ERRORS
  83 };
  84
  85 static void
  86 g_tls_connection_class_init (GTlsConnectionClass *klass)
  87 {
  88   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
  89
  90   gobject_class->get_property = g_tls_connection_get_property;
  91   gobject_class->set_property = g_tls_connection_set_property;
  92
  93   /**
  94    * GTlsConnection:base-io-stream:
  95    *
  96    * The #GIOStream that the connection wraps
  97    *
  98    * Since: 2.28
  99    */
 100   g_object_class_install_property (gobject_class, PROP_BASE_IO_STREAM,
 101                                    g_param_spec_object ("base-io-stream",
 102                                                         P_("Base IOStream"),
 103                                                         P_("The GIOStream that the connection wraps"),
 104                                                         G_TYPE_IO_STREAM,
 105                                                         G_PARAM_READWRITE |
 106                                                         G_PARAM_CONSTRUCT_ONLY |
 107                                                         G_PARAM_STATIC_STRINGS));
 108   /**
 109    * GTlsConnection:use-system-certdb:
 110    *
 111    * Whether or not the system certificate database will be used to
 112    * verify peer certificates. See
 113    * g_tls_connection_set_use_system_certdb().
 114    *
 115    * Since: 2.28
 116    */
 117   g_object_class_install_property (gobject_class, PROP_USE_SYSTEM_CERTDB,
 118                                    g_param_spec_boolean ("use-system-certdb",
 119                                                          P_("Use system certificate database"),
 120                                                          P_("Whether to verify peer certificates against the system certificate database"),
 121                                                          TRUE,
 122                                                          G_PARAM_READWRITE |
 123                                                          G_PARAM_CONSTRUCT |
 124                                                          G_PARAM_STATIC_STRINGS));
 125   /**
 126    * GTlsConnection:require-close-notify:
 127    *
 128    * Whether or not proper TLS close notification is required.
 129    * See g_tls_connection_set_require_close_notify().
 130    *
 131    * Since: 2.28
 132    */
 133   g_object_class_install_property (gobject_class, PROP_REQUIRE_CLOSE_NOTIFY,
 134                                    g_param_spec_boolean ("require-close-notify",
 135                                                          P_("Require close notify"),
 136                                                          P_("Whether to require proper TLS close notification"),
 137                                                          TRUE,
 138                                                          G_PARAM_READWRITE |
 139                                                          G_PARAM_CONSTRUCT |
 140                                                          G_PARAM_STATIC_STRINGS));
 141   /**
 142    * GTlsConnection:rehandshake-mode:
 143    *
 144    * The rehandshaking mode. See
 145    * g_tls_connection_set_rehandshake_mode().
 146    *
 147    * Since: 2.28
 148    */
 149   g_object_class_install_property (gobject_class, PROP_REHANDSHAKE_MODE,
 150                                    g_param_spec_enum ("rehandshake-mode",
 151                                                       P_("Rehandshake mode"),
 152                                                       P_("When to allow rehandshaking"),
 153                                                       G_TYPE_TLS_REHANDSHAKE_MODE,
 154                                                       G_TLS_REHANDSHAKE_SAFELY,
 155                                                       G_PARAM_READWRITE |
 156                                                       G_PARAM_CONSTRUCT |
 157                                                       G_PARAM_STATIC_STRINGS));
 158   /**
 159    * GTlsConnection:certificate:
 160    *
 161    * The connection's certificate; see
 162    * g_tls_connection_set_certificate().
 163    *
 164    * Since: 2.28
 165    */
 166   g_object_class_install_property (gobject_class, PROP_CERTIFICATE,
 167                                    g_param_spec_object ("certificate",
 168                                                         P_("Certificate"),
 169                                                         P_("The connection's certificate"),
 170                                                         G_TYPE_TLS_CERTIFICATE,
 171                                                         G_PARAM_READWRITE |
 172                                                         G_PARAM_STATIC_STRINGS));
 173   /**
 174    * GTlsConnection:peer-certificate:
 175    *
 176    * The connection's peer's certificate, after the TLS handshake has
 177    * completed and the certificate has been accepted. Note in
 178    * particular that this is not yet set during the emission of
 179    * #GTlsConnection::accept-certificate.
 180    *
 181    * (You can watch for a #GObject::notify signal on this property to
 182    * detect when a handshake has occurred.)
 183    *
 184    * Since: 2.28
 185    */
 186   g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE,
 187                                    g_param_spec_object ("peer-certificate",
 188                                                         P_("Peer Certificate"),
 189                                                         P_("The connection's peer's certificate"),
 190                                                         G_TYPE_TLS_CERTIFICATE,
 191                                                         G_PARAM_READABLE |
 192                                                         G_PARAM_STATIC_STRINGS));
 193   /**
 194    * GTlsConnection:peer-certificate-errors:
 195    *
 196    * The errors noticed-and-ignored while verifying
 197    * #GTlsConnection:peer-certificate. Normally this should be 0, but
 198    * it may not be if #GTlsClientConnection:validation-flags is not
 199    * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
 200    * #GTlsConnection::accept-certificate overrode the default
 201    * behavior.
 202    *
 203    * Since: 2.28
 204    */
 205   g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE_ERRORS,
 206                                    g_param_spec_flags ("peer-certificate-errors",
 207                                                        P_("Peer Certificate Errors"),
 208                                                        P_("Errors found with the peer's certificate"),
 209                                                        G_TYPE_TLS_CERTIFICATE_FLAGS,
 210                                                        0,
 211                                                        G_PARAM_READABLE |
 212                                                        G_PARAM_STATIC_STRINGS));
 213
 214   /**
 215    * GTlsConnection::accept-certificate:
 216    * @conn: a #GTlsConnection
 217    * @peer_cert: the peer's #GTlsCertificate
 218    * @errors: the problems with @peer_cert.
 219    *
 220    * Emitted during the TLS handshake after the peer certificate has
 221    * been received. You can examine @peer_cert's certification path by
 222    * calling g_tls_certificate_get_issuer() on it.
 223    *
 224    * For a client-side connection, @peer_cert is the server's
 225    * certificate, and the signal will only be emitted if the
 226    * certificate was not acceptable according to @conn's
 227    * #GTlsClientConnection:validation_flags. If you would like the
 228    * certificate to be accepted despite @errors, return %TRUE from the
 229    * signal handler. Otherwise, if no handler accepts the certificate,
 230    * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
 231    *
 232    * For a server-side connection, @peer_cert is the certificate
 233    * presented by the client, if this was requested via the server's
 234    * #GTlsServerConnection:authentication_mode. On the server side,
 235    * the signal is always emitted when the client presents a
 236    * certificate, and the certificate will only be accepted if a
 237    * handler returns %TRUE.
 238    *
 239    * Note that if this signal is emitted as part of asynchronous I/O
 240    * in the main thread, then you should not attempt to interact with
 241    * the user before returning from the signal handler. If you want to
 242    * let the user decide whether or not to accept the certificate, you
 243    * would have to return %FALSE from the signal handler on the first
 244    * attempt, and then after the connection attempt returns a
 245    * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
 246    * the user decides to accept the certificate, remember that fact,
 247    * create a new connection, and return %TRUE from the signal handler
 248    * the next time.
 249    *
 250    * If you are doing I/O in another thread, you do not
 251    * need to worry about this, and can simply block in the signal
 252    * handler until the UI thread returns an answer.
 253    *
 254    * Return value: %TRUE to accept @peer_cert (which will also
 255    * immediately end the signal emission). %FALSE to allow the signal
 256    * emission to continue, which will cause the handshake to fail if
 257    * no one else overrides it.
 258    *
 259    * Since: 2.28
 260    */
 261   signals[ACCEPT_CERTIFICATE] =
 262     g_signal_new (I_("accept-certificate"),
 263                   G_TYPE_TLS_CONNECTION,
 264                   G_SIGNAL_RUN_LAST,
 265                   G_STRUCT_OFFSET (GTlsConnectionClass, accept_certificate),
 266                   g_signal_accumulator_true_handled, NULL,
 267                   NULL,
 268                   G_TYPE_BOOLEAN, 2,
 269                   G_TYPE_TLS_CERTIFICATE,
 270                   G_TYPE_TLS_CERTIFICATE_FLAGS);
 271 }
 272
 273 static void
 274 g_tls_connection_init (GTlsConnection *conn)
 275 {
 276 }
 277
 278 static void
 279 g_tls_connection_get_property (GObject    *object,
 280                                guint       prop_id,
 281                                GValue     *value,
 282                                GParamSpec *pspec)
 283 {
 284   G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 285 }
 286
 287 static void
 288 g_tls_connection_set_property (GObject      *object,
 289                                guint         prop_id,
 290                                const GValue *value,
 291                                GParamSpec   *pspec)
 292 {
 293   G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 294 }
 295
 296 /**
 297  * g_tls_connection_set_use_system_certdb:
 298  * @conn: a #GTlsConnection
 299  * @use_system_certdb: whether to use the system certificate database
 300  *
 301  * Sets whether @conn uses the system certificate database to verify
 302  * peer certificates. This is %TRUE by default. If set to %FALSE, then
 303  * peer certificate validation will always set the
 304  * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
 305  * #GTlsConnection::accept-certificate will always be emitted on
 306  * client-side connections, unless that bit is not set in
 307  * #GTlsClientConnection:validation-flags).
 308  *
 309  * Since: 2.28
 310  */
 311 void
 312 g_tls_connection_set_use_system_certdb (GTlsConnection *conn,
 313                                         gboolean        use_system_certdb)
 314 {
 315   g_return_if_fail (G_IS_TLS_CONNECTION (conn));
 316
 317   g_object_set (G_OBJECT (conn),
 318                 "use-system-certdb", use_system_certdb,
 319                 NULL);
 320 }
 321
 322 /**
 323  * g_tls_connection_get_use_system_certdb:
 324  * @conn: a #GTlsConnection
 325  *
 326  * Gets whether @conn uses the system certificate database to verify
 327  * peer certificates. See g_tls_connection_set_use_system_certdb().
 328  *
 329  * Return value: whether @conn uses the system certificate database
 330  *
 331  * Since: 2.28
 332  */
 333 gboolean
 334 g_tls_connection_get_use_system_certdb (GTlsConnection *conn)
 335 {
 336   gboolean use_system_certdb;
 337
 338   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
 339
 340   g_object_get (G_OBJECT (conn),
 341                 "use-system-certdb", &use_system_certdb,
 342                 NULL);
 343   return use_system_certdb;
 344 }
 345
 346 /**
 347  * g_tls_connection_set_certificate:
 348  * @conn: a #GTlsConnection
 349  * @certificate: the certificate to use for @conn
 350  *
 351  * This sets the certificate that @conn will present to its peer
 352  * during the TLS handshake. For a #GTlsServerConnection, it is
 353  * mandatory to set this, and that will normally be done at construct
 354  * time.
 355  *
 356  * For a #GTlsClientConnection, this is optional. If a handshake fails
 357  * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
 358  * requires a certificate, and if you try connecting again, you should
 359  * call this method first. You can call
 360  * g_tls_client_connection_get_accepted_cas() on the failed connection
 361  * to get a list of Certificate Authorities that the server will
 362  * accept certificates from.
 363  *
 364  * (It is also possible that a server will allow the connection with
 365  * or without a certificate; in that case, if you don't provide a
 366  * certificate, you can tell that the server requested one by the fact
 367  * that g_tls_client_connection_get_accepted_cas() will return
 368  * non-%NULL.)
 369  *
 370  * Since: 2.28
 371  */
 372 void
 373 g_tls_connection_set_certificate (GTlsConnection  *conn,
 374                                   GTlsCertificate *certificate)
 375 {
 376   g_return_if_fail (G_IS_TLS_CONNECTION (conn));
 377   g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
 378
 379   g_object_set (G_OBJECT (conn), "certificate", certificate, NULL);
 380 }
 381
 382 /**
 383  * g_tls_connection_get_certificate:
 384  * @conn: a #GTlsConnection
 385  *
 386  * Gets @conn's certificate, as set by
 387  * g_tls_connection_set_certificate().
 388  *
 389  * Return value: (transfer none): @conn's certificate, or %NULL
 390  *
 391  * Since: 2.28
 392  */
 393 GTlsCertificate *
 394 g_tls_connection_get_certificate (GTlsConnection *conn)
 395 {
 396   GTlsCertificate *certificate;
 397
 398   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
 399
 400   g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
 401   if (certificate)
 402     g_object_unref (certificate);
 403
 404   return certificate;
 405 }
 406
 407 /**
 408  * g_tls_connection_get_peer_certificate:
 409  * @conn: a #GTlsConnection
 410  *
 411  * Gets @conn's peer's certificate after the handshake has completed.
 412  * (It is not set during the emission of
 413  * #GTlsConnection::accept-certificate.)
 414  *
 415  * Return value: (transfer none): @conn's peer's certificate, or %NULL
 416  *
 417  * Since: 2.28
 418  */
 419 GTlsCertificate *
 420 g_tls_connection_get_peer_certificate (GTlsConnection *conn)
 421 {
 422   GTlsCertificate *peer_certificate;
 423
 424   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
 425
 426   g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
 427   if (peer_certificate)
 428     g_object_unref (peer_certificate);
 429
 430   return peer_certificate;
 431 }
 432
 433 /**
 434  * g_tls_connection_get_peer_certificate_errors:
 435  * @conn: a #GTlsConnection
 436  *
 437  * Gets the errors associated with validating @conn's peer's
 438  * certificate, after the handshake has completed. (It is not set
 439  * during the emission of #GTlsConnection::accept-certificate.)
 440  *
 441  * Return value: @conn's peer's certificate errors
 442  *
 443  * Since: 2.28
 444  */
 445 GTlsCertificateFlags
 446 g_tls_connection_get_peer_certificate_errors (GTlsConnection *conn)
 447 {
 448   GTlsCertificateFlags errors;
 449
 450   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), 0);
 451
 452   g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
 453   return errors;
 454 }
 455
 456 /**
 457  * g_tls_connection_set_require_close_notify:
 458  * @conn: a #GTlsConnection
 459  * @require_close_notify: whether or not to require close notification
 460  *
 461  * Sets whether or not @conn expects a proper TLS close notification
 462  * before the connection is closed. If this is %TRUE (the default),
 463  * then @conn will expect to receive a TLS close notification from its
 464  * peer before the connection is closed, and will return a
 465  * %G_TLS_ERROR_EOF error if the connection is closed without proper
 466  * notification (since this may indicate a network error, or
 467  * man-in-the-middle attack).
 468  *
 469  * In some protocols, the application will know whether or not the
 470  * connection was closed cleanly based on application-level data
 471  * (because the application-level data includes a length field, or is
 472  * somehow self-delimiting); in this case, the close notify is
 473  * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
 474  * in TLS 1.0 it is technically an error, but often done anyway.) You
 475  * can use g_tls_connection_set_require_close_notify() to tell @conn
 476  * to allow an "unannounced" connection close, in which case the close
 477  * will show up as a 0-length read, as in a non-TLS
 478  * #GSocketConnection, and it is up to the application to check that
 479  * the data has been fully received.
 480  *
 481  * Note that this only affects the behavior when the peer closes the
 482  * connection; when the application calls g_io_stream_close() itself
 483  * on @conn, this will send a close notification regardless of the
 484  * setting of this property. If you explicitly want to do an unclean
 485  * close, you can close @conn's #GTlsConnection:base-io-stream rather
 486  * than closing @conn itself.
 487  *
 488  * Since: 2.28
 489  */
 490 void
 491 g_tls_connection_set_require_close_notify (GTlsConnection *conn,
 492                                            gboolean        require_close_notify)
 493 {
 494   g_return_if_fail (G_IS_TLS_CONNECTION (conn));
 495
 496   g_object_set (G_OBJECT (conn),
 497                 "require-close-notify", require_close_notify,
 498                 NULL);
 499 }
 500
 501 /**
 502  * g_tls_connection_get_require_close_notify:
 503  * @conn: a #GTlsConnection
 504  *
 505  * Tests whether or not @conn expects a proper TLS close notification
 506  * when the connection is closed. See
 507  * g_tls_connection_set_require_close_notify() for details.
 508  *
 509  * Return value: %TRUE if @conn requires a proper TLS close
 510  * notification.
 511  *
 512  * Since: 2.28
 513  */
 514 gboolean
 515 g_tls_connection_get_require_close_notify (GTlsConnection *conn)
 516 {
 517   gboolean require_close_notify;
 518
 519   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
 520
 521   g_object_get (G_OBJECT (conn),
 522                 "require-close-notify", &require_close_notify,
 523                 NULL);
 524   return require_close_notify;
 525 }
 526
 527 /**
 528  * g_tls_connection_set_rehandshake_mode:
 529  * @conn: a #GTlsConnection
 530  * @mode: the rehandshaking mode
 531  *
 532  * Sets how @conn behaves with respect to rehandshaking requests.
 533  *
 534  * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
 535  * rehandshake after the initial handshake is complete. (For a client,
 536  * this means it will refuse rehandshake requests from the server, and
 537  * for a server, this means it will close the connection with an error
 538  * if the client attempts to rehandshake.)
 539  *
 540  * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
 541  * rehandshake only if the other end of the connection supports the
 542  * TLS <literal>renegotiation_info</literal> extension. This is the
 543  * default behavior, but means that rehandshaking will not work
 544  * against older implementations that do not support that extension.
 545  *
 546  * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
 547  * rehandshaking even without the
 548  * <literal>renegotiation_info</literal> extension. On the server side
 549  * in particular, this is not recommended, since it leaves the server
 550  * open to certain attacks. However, this mode is necessary if you
 551  * need to allow renegotiation with older client software.
 552  *
 553  * Since: 2.28
 554  */
 555 void
 556 g_tls_connection_set_rehandshake_mode (GTlsConnection       *conn,
 557                                        GTlsRehandshakeMode   mode)
 558 {
 559   g_return_if_fail (G_IS_TLS_CONNECTION (conn));
 560
 561   g_object_set (G_OBJECT (conn),
 562                 "rehandshake-mode", mode,
 563                 NULL);
 564 }
 565
 566 /**
 567  * g_tls_connection_get_rehandshake_mode:
 568  * @conn: a #GTlsConnection
 569  *
 570  * Gets @conn rehandshaking mode. See
 571  * g_tls_connection_set_rehandshake_mode() for details.
 572  *
 573  * Return value: @conn's rehandshaking mode
 574  *
 575  * Since: 2.28
 576  */
 577 GTlsRehandshakeMode
 578 g_tls_connection_get_rehandshake_mode (GTlsConnection       *conn)
 579 {
 580   GTlsRehandshakeMode mode;
 581
 582   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), G_TLS_REHANDSHAKE_NEVER);
 583
 584   g_object_get (G_OBJECT (conn),
 585                 "rehandshake-mode", &mode,
 586                 NULL);
 587   return mode;
 588 }
 589
 590 /**
 591  * g_tls_connection_handshake:
 592  * @conn: a #GTlsConnection
 593  * @cancellable: a #GCancellable, or %NULL
 594  * @error: a #GError, or %NULL
 595  *
 596  * Attempts a TLS handshake on @conn.
 597  *
 598  * On the client side, it is never necessary to call this method;
 599  * although the connection needs to perform a handshake after
 600  * connecting (or after sending a "STARTTLS"-type command) and may
 601  * need to rehandshake later if the server requests it,
 602  * #GTlsConnection will handle this for you automatically when you try
 603  * to send or receive data on the connection. However, you can call
 604  * g_tls_connection_handshake() manually if you want to know for sure
 605  * whether the initial handshake succeeded or failed (as opposed to
 606  * just immediately trying to write to @conn's output stream, in which
 607  * case if it fails, it may not be possible to tell if it failed
 608  * before or after completing the handshake).
 609  *
 610  * Likewise, on the server side, although a handshake is necessary at
 611  * the beginning of the communication, you do not need to call this
 612  * function explicitly unless you want clearer error reporting.
 613  * However, you may call g_tls_connection_handshake() later on to
 614  * renegotiate parameters (encryption methods, etc) with the client.
 615  *
 616  * #GTlsConnection::accept_certificate may be emitted during the
 617  * handshake.
 618  *
 619  * Return value: success or failure
 620  *
 621  * Since: 2.28
 622  */
 623 gboolean
 624 g_tls_connection_handshake (GTlsConnection   *conn,
 625                             GCancellable     *cancellable,
 626                             GError          **error)
 627 {
 628   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
 629
 630   return G_TLS_CONNECTION_GET_CLASS (conn)->handshake (conn, cancellable, error);
 631 }
 632
 633 /**
 634  * g_tls_connection_handshake_async:
 635  * @conn: a #GTlsConnection
 636  * @io_priority: the <link linkend="io-priority">I/O priority</link>
 637  * of the request.
 638  * @cancellable: a #GCancellable, or %NULL
 639  * @callback: callback to call when the handshake is complete
 640  * @user_data: the data to pass to the callback function
 641  *
 642  * Asynchronously performs a TLS handshake on @conn. See
 643  * g_tls_connection_handshake() for more information.
 644  *
 645  * Since: 2.28
 646  */
 647 void
 648 g_tls_connection_handshake_async (GTlsConnection       *conn,
 649                                   int                   io_priority,
 650                                   GCancellable         *cancellable,
 651                                   GAsyncReadyCallback   callback,
 652                                   gpointer              user_data)
 653 {
 654   g_return_if_fail (G_IS_TLS_CONNECTION (conn));
 655
 656   G_TLS_CONNECTION_GET_CLASS (conn)->handshake_async (conn, io_priority,
 657                                                       cancellable,
 658                                                       callback, user_data);
 659 }
 660
 661 /**
 662  * g_tls_connection_handshake_finish:
 663  * @conn: a #GTlsConnection
 664  * @result: a #GAsyncResult.
 665  * @error: a #GError pointer, or %NULL
 666  *
 667  * Finish an asynchronous TLS handshake operation. See
 668  * g_tls_connection_handshake() for more information.
 669  *
 670  * Return value: %TRUE on success, %FALSE on failure, in which
 671  * case @error will be set.
 672  *
 673  * Since: 2.28
 674  */
 675 gboolean
 676 g_tls_connection_handshake_finish (GTlsConnection  *conn,
 677                                    GAsyncResult    *result,
 678                                    GError         **error)
 679 {
 680   g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
 681
 682   return G_TLS_CONNECTION_GET_CLASS (conn)->handshake_finish (conn, result, error);
 683 }
 684
 685 /**
 686  * g_tls_error_quark:
 687  *
 688  * Gets the TLS error quark.
 689  *
 690  * Return value: a #GQuark.
 691  *
 692  * Since: 2.28
 693  */
 694 GQuark
 695 g_tls_error_quark (void)
 696 {
 697   return g_quark_from_static_string ("g-tls-error-quark");
 698 }
 699
 700
 701 /**
 702  * g_tls_connection_emit_accept_certificate:
 703  * @conn: a #GTlsConnection
 704  * @peer_cert: the peer's #GTlsCertificate
 705  * @errors: the problems with @peer_cert
 706  *
 707  * Used by #GTlsConnection implementations to emit the
 708  * #GTlsConnection::accept-certificate signal.
 709  *
 710  * Return value: %TRUE if one of the signal handlers has returned
 711  *     %TRUE to accept @peer_cert
 712  *
 713  * Since: 2.28
 714  */
 715 gboolean
 716 g_tls_connection_emit_accept_certificate (GTlsConnection       *conn,
 717                                           GTlsCertificate      *peer_cert,
 718                                           GTlsCertificateFlags  errors)
 719 {
 720   gboolean accept = FALSE;
 721
 722   g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
 723                  peer_cert, errors, &accept);
 724   return accept;
 725 }