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