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