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