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