LCOV - code coverage report
Current view: top level - glib/gio - gdtlsconnection.c (source / functions) Hit Total Coverage
Test: unnamed Lines: 25 149 16.8 %
Date: 2024-03-26 05:16:46 Functions: 3 29 10.3 %
Branches: 7 28 25.0 %

           Branch data     Line data    Source code
       1                 :            : /* GIO - GLib Input, Output and Streaming Library
       2                 :            :  *
       3                 :            :  * Copyright © 2010 Red Hat, Inc
       4                 :            :  * Copyright © 2015 Collabora, Ltd.
       5                 :            :  *
       6                 :            :  * SPDX-License-Identifier: LGPL-2.1-or-later
       7                 :            :  *
       8                 :            :  * This library is free software; you can redistribute it and/or
       9                 :            :  * modify it under the terms of the GNU Lesser General Public
      10                 :            :  * License as published by the Free Software Foundation; either
      11                 :            :  * version 2.1 of the License, or (at your option) any later version.
      12                 :            :  *
      13                 :            :  * This library is distributed in the hope that it will be useful,
      14                 :            :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      15                 :            :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      16                 :            :  * Lesser General Public License for more details.
      17                 :            :  *
      18                 :            :  * You should have received a copy of the GNU Lesser General
      19                 :            :  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
      20                 :            :  */
      21                 :            : 
      22                 :            : #include "config.h"
      23                 :            : #include "glib.h"
      24                 :            : 
      25                 :            : #include "gdtlsconnection.h"
      26                 :            : #include "gcancellable.h"
      27                 :            : #include "gioenumtypes.h"
      28                 :            : #include "gsocket.h"
      29                 :            : #include "gtlsbackend.h"
      30                 :            : #include "gtlscertificate.h"
      31                 :            : #include "gtlsconnection.h"
      32                 :            : #include "gdtlsclientconnection.h"
      33                 :            : #include "gtlsdatabase.h"
      34                 :            : #include "gtlsinteraction.h"
      35                 :            : #include "glibintl.h"
      36                 :            : #include "gmarshal-internal.h"
      37                 :            : 
      38                 :            : /**
      39                 :            :  * GDtlsConnection:
      40                 :            :  *
      41                 :            :  * `GDtlsConnection` is the base DTLS connection class type, which wraps
      42                 :            :  * a [iface@Gio.DatagramBased] and provides DTLS encryption on top of it. Its
      43                 :            :  * subclasses, [iface@Gio.DtlsClientConnection] and
      44                 :            :  * [iface@Gio.DtlsServerConnection], implement client-side and server-side DTLS,
      45                 :            :  * respectively.
      46                 :            :  *
      47                 :            :  * For TLS support, see [class@Gio.TlsConnection].
      48                 :            :  *
      49                 :            :  * As DTLS is datagram based, `GDtlsConnection` implements
      50                 :            :  * [iface@Gio.DatagramBased], presenting a datagram-socket-like API for the
      51                 :            :  * encrypted connection. This operates over a base datagram connection, which is
      52                 :            :  * also a `GDatagramBased` ([property@Gio.DtlsConnection:base-socket]).
      53                 :            :  *
      54                 :            :  * To close a DTLS connection, use [method@Gio.DtlsConnection.close].
      55                 :            :  *
      56                 :            :  * Neither [iface@Gio.DtlsServerConnection] or [iface@Gio.DtlsClientConnection]
      57                 :            :  * set the peer address on their base [iface@Gio.DatagramBased] if it is a
      58                 :            :  * [class@Gio.Socket] — it is up to the caller to do that if they wish. If they
      59                 :            :  * do not, and [method@Gio.Socket.close] is called on the base socket, the
      60                 :            :  * `GDtlsConnection` will not raise a `G_IO_ERROR_NOT_CONNECTED` error on
      61                 :            :  * further I/O.
      62                 :            :  *
      63                 :            :  * Since: 2.48
      64                 :            :  */
      65   [ +  +  +  -  :         20 : G_DEFINE_INTERFACE (GDtlsConnection, g_dtls_connection, G_TYPE_DATAGRAM_BASED)
             +  +  +  - ]
      66                 :            : 
      67                 :            : enum {
      68                 :            :   ACCEPT_CERTIFICATE,
      69                 :            :   LAST_SIGNAL
      70                 :            : };
      71                 :            : 
      72                 :            : static guint signals[LAST_SIGNAL] = { 0 };
      73                 :            : 
      74                 :            : enum {
      75                 :            :   PROP_BASE_SOCKET = 1,
      76                 :            :   PROP_REQUIRE_CLOSE_NOTIFY,
      77                 :            :   PROP_REHANDSHAKE_MODE,
      78                 :            :   PROP_DATABASE,
      79                 :            :   PROP_INTERACTION,
      80                 :            :   PROP_CERTIFICATE,
      81                 :            :   PROP_PEER_CERTIFICATE,
      82                 :            :   PROP_PEER_CERTIFICATE_ERRORS,
      83                 :            :   PROP_PROTOCOL_VERSION,
      84                 :            :   PROP_CIPHERSUITE_NAME,
      85                 :            : };
      86                 :            : 
      87                 :            : static void
      88                 :          3 : g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
      89                 :            : {
      90                 :            :   /**
      91                 :            :    * GDtlsConnection:base-socket:
      92                 :            :    *
      93                 :            :    * The #GDatagramBased that the connection wraps. Note that this may be any
      94                 :            :    * implementation of #GDatagramBased, not just a #GSocket.
      95                 :            :    *
      96                 :            :    * Since: 2.48
      97                 :            :    */
      98                 :          3 :   g_object_interface_install_property (iface,
      99                 :            :                                        g_param_spec_object ("base-socket", NULL, NULL,
     100                 :            :                                                             G_TYPE_DATAGRAM_BASED,
     101                 :            :                                                             G_PARAM_READWRITE |
     102                 :            :                                                             G_PARAM_CONSTRUCT_ONLY |
     103                 :            :                                                             G_PARAM_STATIC_STRINGS));
     104                 :            :   /**
     105                 :            :    * GDtlsConnection:database: (nullable)
     106                 :            :    *
     107                 :            :    * The certificate database to use when verifying this TLS connection.
     108                 :            :    * If no certificate database is set, then the default database will be
     109                 :            :    * used. See g_tls_backend_get_default_database().
     110                 :            :    *
     111                 :            :    * When using a non-default database, #GDtlsConnection must fall back to using
     112                 :            :    * the #GTlsDatabase to perform certificate verification using
     113                 :            :    * g_tls_database_verify_chain(), which means certificate verification will
     114                 :            :    * not be able to make use of TLS session context. This may be less secure.
     115                 :            :    * For example, if you create your own #GTlsDatabase that just wraps the
     116                 :            :    * default #GTlsDatabase, you might expect that you have not changed anything,
     117                 :            :    * but this is not true because you may have altered the behavior of
     118                 :            :    * #GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the
     119                 :            :    * documentation of g_tls_database_verify_chain() for more details on specific
     120                 :            :    * security checks that may not be performed. Accordingly, setting a
     121                 :            :    * non-default database is discouraged except for specialty applications with
     122                 :            :    * unusual security requirements.
     123                 :            :    *
     124                 :            :    * Since: 2.48
     125                 :            :    */
     126                 :          3 :   g_object_interface_install_property (iface,
     127                 :            :                                        g_param_spec_object ("database", NULL, NULL,
     128                 :            :                                                             G_TYPE_TLS_DATABASE,
     129                 :            :                                                             G_PARAM_READWRITE |
     130                 :            :                                                             G_PARAM_STATIC_STRINGS));
     131                 :            :   /**
     132                 :            :    * GDtlsConnection:interaction: (nullable)
     133                 :            :    *
     134                 :            :    * A #GTlsInteraction object to be used when the connection or certificate
     135                 :            :    * database need to interact with the user. This will be used to prompt the
     136                 :            :    * user for passwords where necessary.
     137                 :            :    *
     138                 :            :    * Since: 2.48
     139                 :            :    */
     140                 :          3 :   g_object_interface_install_property (iface,
     141                 :            :                                        g_param_spec_object ("interaction", NULL, NULL,
     142                 :            :                                                             G_TYPE_TLS_INTERACTION,
     143                 :            :                                                             G_PARAM_READWRITE |
     144                 :            :                                                             G_PARAM_STATIC_STRINGS));
     145                 :            :   /**
     146                 :            :    * GDtlsConnection:require-close-notify:
     147                 :            :    *
     148                 :            :    * Whether or not proper TLS close notification is required.
     149                 :            :    * See g_dtls_connection_set_require_close_notify().
     150                 :            :    *
     151                 :            :    * Since: 2.48
     152                 :            :    */
     153                 :          3 :   g_object_interface_install_property (iface,
     154                 :            :                                        g_param_spec_boolean ("require-close-notify", NULL, NULL,
     155                 :            :                                                              TRUE,
     156                 :            :                                                              G_PARAM_READWRITE |
     157                 :            :                                                              G_PARAM_CONSTRUCT |
     158                 :            :                                                              G_PARAM_STATIC_STRINGS));
     159                 :            :   /**
     160                 :            :    * GDtlsConnection:rehandshake-mode:
     161                 :            :    *
     162                 :            :    * The rehandshaking mode. See
     163                 :            :    * g_dtls_connection_set_rehandshake_mode().
     164                 :            :    *
     165                 :            :    * Since: 2.48
     166                 :            :    *
     167                 :            :    * Deprecated: 2.60: The rehandshake mode is ignored.
     168                 :            :    */
     169                 :          3 :   g_object_interface_install_property (iface,
     170                 :            :                                        g_param_spec_enum ("rehandshake-mode", NULL, NULL,
     171                 :            :                                                           G_TYPE_TLS_REHANDSHAKE_MODE,
     172                 :            :                                                           G_TLS_REHANDSHAKE_NEVER,
     173                 :            :                                                           G_PARAM_READWRITE |
     174                 :            :                                                           G_PARAM_CONSTRUCT |
     175                 :            :                                                           G_PARAM_STATIC_STRINGS |
     176                 :            :                                                           G_PARAM_DEPRECATED));
     177                 :            :   /**
     178                 :            :    * GDtlsConnection:certificate:
     179                 :            :    *
     180                 :            :    * The connection's certificate; see
     181                 :            :    * g_dtls_connection_set_certificate().
     182                 :            :    *
     183                 :            :    * Since: 2.48
     184                 :            :    */
     185                 :          3 :   g_object_interface_install_property (iface,
     186                 :            :                                        g_param_spec_object ("certificate", NULL, NULL,
     187                 :            :                                                             G_TYPE_TLS_CERTIFICATE,
     188                 :            :                                                             G_PARAM_READWRITE |
     189                 :            :                                                             G_PARAM_STATIC_STRINGS));
     190                 :            :   /**
     191                 :            :    * GDtlsConnection:peer-certificate: (nullable)
     192                 :            :    *
     193                 :            :    * The connection's peer's certificate, after the TLS handshake has
     194                 :            :    * completed or failed. Note in particular that this is not yet set
     195                 :            :    * during the emission of #GDtlsConnection::accept-certificate.
     196                 :            :    *
     197                 :            :    * (You can watch for a #GObject::notify signal on this property to
     198                 :            :    * detect when a handshake has occurred.)
     199                 :            :    *
     200                 :            :    * Since: 2.48
     201                 :            :    */
     202                 :          3 :   g_object_interface_install_property (iface,
     203                 :            :                                        g_param_spec_object ("peer-certificate", NULL, NULL,
     204                 :            :                                                             G_TYPE_TLS_CERTIFICATE,
     205                 :            :                                                             G_PARAM_READABLE |
     206                 :            :                                                             G_PARAM_STATIC_STRINGS));
     207                 :            :   /**
     208                 :            :    * GDtlsConnection:peer-certificate-errors:
     209                 :            :    *
     210                 :            :    * The errors noticed while verifying
     211                 :            :    * #GDtlsConnection:peer-certificate. Normally this should be 0, but
     212                 :            :    * it may not be if #GDtlsClientConnection:validation-flags is not
     213                 :            :    * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
     214                 :            :    * #GDtlsConnection::accept-certificate overrode the default
     215                 :            :    * behavior.
     216                 :            :    *
     217                 :            :    * GLib guarantees that if certificate verification fails, at least
     218                 :            :    * one error will be set, but it does not guarantee that all possible
     219                 :            :    * errors will be set. Accordingly, you may not safely decide to
     220                 :            :    * ignore any particular type of error. For example, it would be
     221                 :            :    * incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
     222                 :            :    * expired certificates, because this could potentially be the only
     223                 :            :    * error flag set even if other problems exist with the certificate.
     224                 :            :    *
     225                 :            :    * Since: 2.48
     226                 :            :    */
     227                 :          3 :   g_object_interface_install_property (iface,
     228                 :            :                                        g_param_spec_flags ("peer-certificate-errors", NULL, NULL,
     229                 :            :                                                            G_TYPE_TLS_CERTIFICATE_FLAGS,
     230                 :            :                                                            0,
     231                 :            :                                                            G_PARAM_READABLE |
     232                 :            :                                                            G_PARAM_STATIC_STRINGS));
     233                 :            :   /**
     234                 :            :    * GDtlsConnection:advertised-protocols: (nullable)
     235                 :            :    *
     236                 :            :    * The list of application-layer protocols that the connection
     237                 :            :    * advertises that it is willing to speak. See
     238                 :            :    * g_dtls_connection_set_advertised_protocols().
     239                 :            :    *
     240                 :            :    * Since: 2.60
     241                 :            :    */
     242                 :          3 :   g_object_interface_install_property (iface,
     243                 :            :                                        g_param_spec_boxed ("advertised-protocols", NULL, NULL,
     244                 :            :                                                            G_TYPE_STRV,
     245                 :            :                                                            G_PARAM_READWRITE |
     246                 :            :                                                            G_PARAM_STATIC_STRINGS));
     247                 :            :   /**
     248                 :            :    * GDtlsConnection:negotiated-protocol:
     249                 :            :    *
     250                 :            :    * The application-layer protocol negotiated during the TLS
     251                 :            :    * handshake. See g_dtls_connection_get_negotiated_protocol().
     252                 :            :    *
     253                 :            :    * Since: 2.60
     254                 :            :    */
     255                 :          3 :   g_object_interface_install_property (iface,
     256                 :            :                                        g_param_spec_string ("negotiated-protocol", NULL, NULL,
     257                 :            :                                                             NULL,
     258                 :            :                                                             G_PARAM_READABLE |
     259                 :            :                                                             G_PARAM_STATIC_STRINGS));
     260                 :            : 
     261                 :            :   /**
     262                 :            :    * GDtlsConnection:protocol-version:
     263                 :            :    *
     264                 :            :    * The DTLS protocol version in use. See g_dtls_connection_get_protocol_version().
     265                 :            :    *
     266                 :            :    * Since: 2.70
     267                 :            :    */
     268                 :          3 :   g_object_interface_install_property (iface,
     269                 :            :                                        g_param_spec_enum ("protocol-version", NULL, NULL,
     270                 :            :                                                           G_TYPE_TLS_PROTOCOL_VERSION,
     271                 :            :                                                           G_TLS_PROTOCOL_VERSION_UNKNOWN,
     272                 :            :                                                           G_PARAM_READABLE |
     273                 :            :                                                           G_PARAM_STATIC_STRINGS));
     274                 :            : 
     275                 :            :   /**
     276                 :            :    * GDtlsConnection:ciphersuite-name: (nullable)
     277                 :            :    *
     278                 :            :    * The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name().
     279                 :            :    *
     280                 :            :    * Since: 2.70
     281                 :            :    */
     282                 :          3 :   g_object_interface_install_property (iface,
     283                 :            :                                        g_param_spec_string ("ciphersuite-name", NULL, NULL,
     284                 :            :                                                             NULL,
     285                 :            :                                                             G_PARAM_READABLE |
     286                 :            :                                                             G_PARAM_STATIC_STRINGS));
     287                 :            : 
     288                 :            :   /**
     289                 :            :    * GDtlsConnection::accept-certificate:
     290                 :            :    * @conn: a #GDtlsConnection
     291                 :            :    * @peer_cert: the peer's #GTlsCertificate
     292                 :            :    * @errors: the problems with @peer_cert.
     293                 :            :    *
     294                 :            :    * Emitted during the TLS handshake after the peer certificate has
     295                 :            :    * been received. You can examine @peer_cert's certification path by
     296                 :            :    * calling g_tls_certificate_get_issuer() on it.
     297                 :            :    *
     298                 :            :    * For a client-side connection, @peer_cert is the server's
     299                 :            :    * certificate, and the signal will only be emitted if the
     300                 :            :    * certificate was not acceptable according to @conn's
     301                 :            :    * #GDtlsClientConnection:validation_flags. If you would like the
     302                 :            :    * certificate to be accepted despite @errors, return %TRUE from the
     303                 :            :    * signal handler. Otherwise, if no handler accepts the certificate,
     304                 :            :    * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
     305                 :            :    *
     306                 :            :    * GLib guarantees that if certificate verification fails, this signal
     307                 :            :    * will be emitted with at least one error will be set in @errors, but
     308                 :            :    * it does not guarantee that all possible errors will be set.
     309                 :            :    * Accordingly, you may not safely decide to ignore any particular
     310                 :            :    * type of error. For example, it would be incorrect to ignore
     311                 :            :    * %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired
     312                 :            :    * certificates, because this could potentially be the only error flag
     313                 :            :    * set even if other problems exist with the certificate.
     314                 :            :    *
     315                 :            :    * For a server-side connection, @peer_cert is the certificate
     316                 :            :    * presented by the client, if this was requested via the server's
     317                 :            :    * #GDtlsServerConnection:authentication_mode. On the server side,
     318                 :            :    * the signal is always emitted when the client presents a
     319                 :            :    * certificate, and the certificate will only be accepted if a
     320                 :            :    * handler returns %TRUE.
     321                 :            :    *
     322                 :            :    * Note that if this signal is emitted as part of asynchronous I/O
     323                 :            :    * in the main thread, then you should not attempt to interact with
     324                 :            :    * the user before returning from the signal handler. If you want to
     325                 :            :    * let the user decide whether or not to accept the certificate, you
     326                 :            :    * would have to return %FALSE from the signal handler on the first
     327                 :            :    * attempt, and then after the connection attempt returns a
     328                 :            :    * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
     329                 :            :    * if the user decides to accept the certificate, remember that fact,
     330                 :            :    * create a new connection, and return %TRUE from the signal handler
     331                 :            :    * the next time.
     332                 :            :    *
     333                 :            :    * If you are doing I/O in another thread, you do not
     334                 :            :    * need to worry about this, and can simply block in the signal
     335                 :            :    * handler until the UI thread returns an answer.
     336                 :            :    *
     337                 :            :    * Returns: %TRUE to accept @peer_cert (which will also
     338                 :            :    * immediately end the signal emission). %FALSE to allow the signal
     339                 :            :    * emission to continue, which will cause the handshake to fail if
     340                 :            :    * no one else overrides it.
     341                 :            :    *
     342                 :            :    * Since: 2.48
     343                 :            :    */
     344                 :          3 :   signals[ACCEPT_CERTIFICATE] =
     345                 :          3 :     g_signal_new (I_("accept-certificate"),
     346                 :            :                   G_TYPE_DTLS_CONNECTION,
     347                 :            :                   G_SIGNAL_RUN_LAST,
     348                 :            :                   G_STRUCT_OFFSET (GDtlsConnectionInterface, accept_certificate),
     349                 :            :                   g_signal_accumulator_true_handled, NULL,
     350                 :            :                   _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGS,
     351                 :            :                   G_TYPE_BOOLEAN, 2,
     352                 :            :                   G_TYPE_TLS_CERTIFICATE,
     353                 :            :                   G_TYPE_TLS_CERTIFICATE_FLAGS);
     354                 :          3 :   g_signal_set_va_marshaller (signals[ACCEPT_CERTIFICATE],
     355                 :            :                               G_TYPE_FROM_INTERFACE (iface),
     356                 :            :                               _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGSv);
     357                 :          3 : }
     358                 :            : 
     359                 :            : /**
     360                 :            :  * g_dtls_connection_set_database:
     361                 :            :  * @conn: a #GDtlsConnection
     362                 :            :  * @database: (nullable): a #GTlsDatabase
     363                 :            :  *
     364                 :            :  * Sets the certificate database that is used to verify peer certificates.
     365                 :            :  * This is set to the default database by default. See
     366                 :            :  * g_tls_backend_get_default_database(). If set to %NULL, then
     367                 :            :  * peer certificate validation will always set the
     368                 :            :  * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
     369                 :            :  * #GDtlsConnection::accept-certificate will always be emitted on
     370                 :            :  * client-side connections, unless that bit is not set in
     371                 :            :  * #GDtlsClientConnection:validation-flags).
     372                 :            :  *
     373                 :            :  * There are nonintuitive security implications when using a non-default
     374                 :            :  * database. See #GDtlsConnection:database for details.
     375                 :            :  *
     376                 :            :  * Since: 2.48
     377                 :            :  */
     378                 :            : void
     379                 :          0 : g_dtls_connection_set_database (GDtlsConnection *conn,
     380                 :            :                                 GTlsDatabase    *database)
     381                 :            : {
     382                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     383                 :          0 :   g_return_if_fail (database == NULL || G_IS_TLS_DATABASE (database));
     384                 :            : 
     385                 :          0 :   g_object_set (G_OBJECT (conn),
     386                 :            :                 "database", database,
     387                 :            :                 NULL);
     388                 :            : }
     389                 :            : 
     390                 :            : /**
     391                 :            :  * g_dtls_connection_get_database:
     392                 :            :  * @conn: a #GDtlsConnection
     393                 :            :  *
     394                 :            :  * Gets the certificate database that @conn uses to verify
     395                 :            :  * peer certificates. See g_dtls_connection_set_database().
     396                 :            :  *
     397                 :            :  * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL
     398                 :            :  *
     399                 :            :  * Since: 2.48
     400                 :            :  */
     401                 :            : GTlsDatabase*
     402                 :          0 : g_dtls_connection_get_database (GDtlsConnection *conn)
     403                 :            : {
     404                 :          0 :   GTlsDatabase *database = NULL;
     405                 :            : 
     406                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
     407                 :            : 
     408                 :          0 :   g_object_get (G_OBJECT (conn),
     409                 :            :                 "database", &database,
     410                 :            :                 NULL);
     411         [ #  # ]:          0 :   if (database)
     412                 :          0 :     g_object_unref (database);
     413                 :          0 :   return database;
     414                 :            : }
     415                 :            : 
     416                 :            : /**
     417                 :            :  * g_dtls_connection_set_certificate:
     418                 :            :  * @conn: a #GDtlsConnection
     419                 :            :  * @certificate: the certificate to use for @conn
     420                 :            :  *
     421                 :            :  * This sets the certificate that @conn will present to its peer
     422                 :            :  * during the TLS handshake. For a #GDtlsServerConnection, it is
     423                 :            :  * mandatory to set this, and that will normally be done at construct
     424                 :            :  * time.
     425                 :            :  *
     426                 :            :  * For a #GDtlsClientConnection, this is optional. If a handshake fails
     427                 :            :  * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
     428                 :            :  * requires a certificate, and if you try connecting again, you should
     429                 :            :  * call this method first. You can call
     430                 :            :  * g_dtls_client_connection_get_accepted_cas() on the failed connection
     431                 :            :  * to get a list of Certificate Authorities that the server will
     432                 :            :  * accept certificates from.
     433                 :            :  *
     434                 :            :  * (It is also possible that a server will allow the connection with
     435                 :            :  * or without a certificate; in that case, if you don't provide a
     436                 :            :  * certificate, you can tell that the server requested one by the fact
     437                 :            :  * that g_dtls_client_connection_get_accepted_cas() will return
     438                 :            :  * non-%NULL.)
     439                 :            :  *
     440                 :            :  * Since: 2.48
     441                 :            :  */
     442                 :            : void
     443                 :          0 : g_dtls_connection_set_certificate (GDtlsConnection *conn,
     444                 :            :                                    GTlsCertificate *certificate)
     445                 :            : {
     446                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     447                 :          0 :   g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
     448                 :            : 
     449                 :          0 :   g_object_set (G_OBJECT (conn), "certificate", certificate, NULL);
     450                 :            : }
     451                 :            : 
     452                 :            : /**
     453                 :            :  * g_dtls_connection_get_certificate:
     454                 :            :  * @conn: a #GDtlsConnection
     455                 :            :  *
     456                 :            :  * Gets @conn's certificate, as set by
     457                 :            :  * g_dtls_connection_set_certificate().
     458                 :            :  *
     459                 :            :  * Returns: (transfer none) (nullable): @conn's certificate, or %NULL
     460                 :            :  *
     461                 :            :  * Since: 2.48
     462                 :            :  */
     463                 :            : GTlsCertificate *
     464                 :          0 : g_dtls_connection_get_certificate (GDtlsConnection *conn)
     465                 :            : {
     466                 :            :   GTlsCertificate *certificate;
     467                 :            : 
     468                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
     469                 :            : 
     470                 :          0 :   g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
     471         [ #  # ]:          0 :   if (certificate)
     472                 :          0 :     g_object_unref (certificate);
     473                 :            : 
     474                 :          0 :   return certificate;
     475                 :            : }
     476                 :            : 
     477                 :            : /**
     478                 :            :  * g_dtls_connection_set_interaction:
     479                 :            :  * @conn: a connection
     480                 :            :  * @interaction: (nullable): an interaction object, or %NULL
     481                 :            :  *
     482                 :            :  * Set the object that will be used to interact with the user. It will be used
     483                 :            :  * for things like prompting the user for passwords.
     484                 :            :  *
     485                 :            :  * The @interaction argument will normally be a derived subclass of
     486                 :            :  * #GTlsInteraction. %NULL can also be provided if no user interaction
     487                 :            :  * should occur for this connection.
     488                 :            :  *
     489                 :            :  * Since: 2.48
     490                 :            :  */
     491                 :            : void
     492                 :          0 : g_dtls_connection_set_interaction (GDtlsConnection *conn,
     493                 :            :                                    GTlsInteraction *interaction)
     494                 :            : {
     495                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     496                 :          0 :   g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
     497                 :            : 
     498                 :          0 :   g_object_set (G_OBJECT (conn), "interaction", interaction, NULL);
     499                 :            : }
     500                 :            : 
     501                 :            : /**
     502                 :            :  * g_dtls_connection_get_interaction:
     503                 :            :  * @conn: a connection
     504                 :            :  *
     505                 :            :  * Get the object that will be used to interact with the user. It will be used
     506                 :            :  * for things like prompting the user for passwords. If %NULL is returned, then
     507                 :            :  * no user interaction will occur for this connection.
     508                 :            :  *
     509                 :            :  * Returns: (transfer none) (nullable): The interaction object.
     510                 :            :  *
     511                 :            :  * Since: 2.48
     512                 :            :  */
     513                 :            : GTlsInteraction *
     514                 :          0 : g_dtls_connection_get_interaction (GDtlsConnection       *conn)
     515                 :            : {
     516                 :          0 :   GTlsInteraction *interaction = NULL;
     517                 :            : 
     518                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
     519                 :            : 
     520                 :          0 :   g_object_get (G_OBJECT (conn), "interaction", &interaction, NULL);
     521         [ #  # ]:          0 :   if (interaction)
     522                 :          0 :     g_object_unref (interaction);
     523                 :            : 
     524                 :          0 :   return interaction;
     525                 :            : }
     526                 :            : 
     527                 :            : /**
     528                 :            :  * g_dtls_connection_get_peer_certificate:
     529                 :            :  * @conn: a #GDtlsConnection
     530                 :            :  *
     531                 :            :  * Gets @conn's peer's certificate after the handshake has completed
     532                 :            :  * or failed. (It is not set during the emission of
     533                 :            :  * #GDtlsConnection::accept-certificate.)
     534                 :            :  *
     535                 :            :  * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
     536                 :            :  *
     537                 :            :  * Since: 2.48
     538                 :            :  */
     539                 :            : GTlsCertificate *
     540                 :          0 : g_dtls_connection_get_peer_certificate (GDtlsConnection *conn)
     541                 :            : {
     542                 :            :   GTlsCertificate *peer_certificate;
     543                 :            : 
     544                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
     545                 :            : 
     546                 :          0 :   g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
     547         [ #  # ]:          0 :   if (peer_certificate)
     548                 :          0 :     g_object_unref (peer_certificate);
     549                 :            : 
     550                 :          0 :   return peer_certificate;
     551                 :            : }
     552                 :            : 
     553                 :            : /**
     554                 :            :  * g_dtls_connection_get_peer_certificate_errors:
     555                 :            :  * @conn: a #GDtlsConnection
     556                 :            :  *
     557                 :            :  * Gets the errors associated with validating @conn's peer's
     558                 :            :  * certificate, after the handshake has completed or failed. (It is
     559                 :            :  * not set during the emission of #GDtlsConnection::accept-certificate.)
     560                 :            :  *
     561                 :            :  * Returns: @conn's peer's certificate errors
     562                 :            :  *
     563                 :            :  * Since: 2.48
     564                 :            :  */
     565                 :            : GTlsCertificateFlags
     566                 :          0 : g_dtls_connection_get_peer_certificate_errors (GDtlsConnection *conn)
     567                 :            : {
     568                 :            :   GTlsCertificateFlags errors;
     569                 :            : 
     570                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), 0);
     571                 :            : 
     572                 :          0 :   g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
     573                 :          0 :   return errors;
     574                 :            : }
     575                 :            : 
     576                 :            : /**
     577                 :            :  * g_dtls_connection_set_require_close_notify:
     578                 :            :  * @conn: a #GDtlsConnection
     579                 :            :  * @require_close_notify: whether or not to require close notification
     580                 :            :  *
     581                 :            :  * Sets whether or not @conn expects a proper TLS close notification
     582                 :            :  * before the connection is closed. If this is %TRUE (the default),
     583                 :            :  * then @conn will expect to receive a TLS close notification from its
     584                 :            :  * peer before the connection is closed, and will return a
     585                 :            :  * %G_TLS_ERROR_EOF error if the connection is closed without proper
     586                 :            :  * notification (since this may indicate a network error, or
     587                 :            :  * man-in-the-middle attack).
     588                 :            :  *
     589                 :            :  * In some protocols, the application will know whether or not the
     590                 :            :  * connection was closed cleanly based on application-level data
     591                 :            :  * (because the application-level data includes a length field, or is
     592                 :            :  * somehow self-delimiting); in this case, the close notify is
     593                 :            :  * redundant and may be omitted. You
     594                 :            :  * can use g_dtls_connection_set_require_close_notify() to tell @conn
     595                 :            :  * to allow an "unannounced" connection close, in which case the close
     596                 :            :  * will show up as a 0-length read, as in a non-TLS
     597                 :            :  * #GDatagramBased, and it is up to the application to check that
     598                 :            :  * the data has been fully received.
     599                 :            :  *
     600                 :            :  * Note that this only affects the behavior when the peer closes the
     601                 :            :  * connection; when the application calls g_dtls_connection_close_async() on
     602                 :            :  * @conn itself, this will send a close notification regardless of the
     603                 :            :  * setting of this property. If you explicitly want to do an unclean
     604                 :            :  * close, you can close @conn's #GDtlsConnection:base-socket rather
     605                 :            :  * than closing @conn itself.
     606                 :            :  *
     607                 :            :  * Since: 2.48
     608                 :            :  */
     609                 :            : void
     610                 :          0 : g_dtls_connection_set_require_close_notify (GDtlsConnection *conn,
     611                 :            :                                             gboolean         require_close_notify)
     612                 :            : {
     613                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     614                 :            : 
     615                 :          0 :   g_object_set (G_OBJECT (conn),
     616                 :            :                 "require-close-notify", require_close_notify,
     617                 :            :                 NULL);
     618                 :            : }
     619                 :            : 
     620                 :            : /**
     621                 :            :  * g_dtls_connection_get_require_close_notify:
     622                 :            :  * @conn: a #GDtlsConnection
     623                 :            :  *
     624                 :            :  * Tests whether or not @conn expects a proper TLS close notification
     625                 :            :  * when the connection is closed. See
     626                 :            :  * g_dtls_connection_set_require_close_notify() for details.
     627                 :            :  *
     628                 :            :  * Returns: %TRUE if @conn requires a proper TLS close notification.
     629                 :            :  *
     630                 :            :  * Since: 2.48
     631                 :            :  */
     632                 :            : gboolean
     633                 :          0 : g_dtls_connection_get_require_close_notify (GDtlsConnection *conn)
     634                 :            : {
     635                 :            :   gboolean require_close_notify;
     636                 :            : 
     637                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), TRUE);
     638                 :            : 
     639                 :          0 :   g_object_get (G_OBJECT (conn),
     640                 :            :                 "require-close-notify", &require_close_notify,
     641                 :            :                 NULL);
     642                 :          0 :   return require_close_notify;
     643                 :            : }
     644                 :            : 
     645                 :            : /**
     646                 :            :  * g_dtls_connection_set_rehandshake_mode:
     647                 :            :  * @conn: a #GDtlsConnection
     648                 :            :  * @mode: the rehandshaking mode
     649                 :            :  *
     650                 :            :  * Since GLib 2.64, changing the rehandshake mode is no longer supported
     651                 :            :  * and will have no effect. With TLS 1.3, rehandshaking has been removed from
     652                 :            :  * the TLS protocol, replaced by separate post-handshake authentication and
     653                 :            :  * rekey operations.
     654                 :            :  *
     655                 :            :  * Since: 2.48
     656                 :            :  *
     657                 :            :  * Deprecated: 2.60. Changing the rehandshake mode is no longer
     658                 :            :  *   required for compatibility. Also, rehandshaking has been removed
     659                 :            :  *   from the TLS protocol in TLS 1.3.
     660                 :            :  */
     661                 :            : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
     662                 :            : void
     663                 :          0 : g_dtls_connection_set_rehandshake_mode (GDtlsConnection     *conn,
     664                 :            :                                         GTlsRehandshakeMode  mode)
     665                 :            : {
     666                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     667                 :            : 
     668                 :          0 :   g_object_set (G_OBJECT (conn),
     669                 :            :                 "rehandshake-mode", G_TLS_REHANDSHAKE_SAFELY,
     670                 :            :                 NULL);
     671                 :            : }
     672                 :            : G_GNUC_END_IGNORE_DEPRECATIONS
     673                 :            : 
     674                 :            : /**
     675                 :            :  * g_dtls_connection_get_rehandshake_mode:
     676                 :            :  * @conn: a #GDtlsConnection
     677                 :            :  *
     678                 :            :  * Gets @conn rehandshaking mode. See
     679                 :            :  * g_dtls_connection_set_rehandshake_mode() for details.
     680                 :            :  *
     681                 :            :  * Returns: %G_TLS_REHANDSHAKE_SAFELY
     682                 :            :  *
     683                 :            :  * Since: 2.48
     684                 :            :  *
     685                 :            :  * Deprecated: 2.64. Changing the rehandshake mode is no longer
     686                 :            :  *   required for compatibility. Also, rehandshaking has been removed
     687                 :            :  *   from the TLS protocol in TLS 1.3.
     688                 :            :  */
     689                 :            : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
     690                 :            : GTlsRehandshakeMode
     691                 :          0 : g_dtls_connection_get_rehandshake_mode (GDtlsConnection *conn)
     692                 :            : {
     693                 :            :   GTlsRehandshakeMode mode;
     694                 :            : 
     695                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), G_TLS_REHANDSHAKE_SAFELY);
     696                 :            : 
     697                 :            :   /* Continue to call g_object_get(), even though the return value is
     698                 :            :    * ignored, so that behavior doesn’t change for derived classes.
     699                 :            :    */
     700                 :          0 :   g_object_get (G_OBJECT (conn),
     701                 :            :                 "rehandshake-mode", &mode,
     702                 :            :                 NULL);
     703                 :          0 :   return G_TLS_REHANDSHAKE_SAFELY;
     704                 :            : }
     705                 :            : G_GNUC_END_IGNORE_DEPRECATIONS
     706                 :            : 
     707                 :            : /**
     708                 :            :  * g_dtls_connection_handshake:
     709                 :            :  * @conn: a #GDtlsConnection
     710                 :            :  * @cancellable: (nullable): a #GCancellable, or %NULL
     711                 :            :  * @error: a #GError, or %NULL
     712                 :            :  *
     713                 :            :  * Attempts a TLS handshake on @conn.
     714                 :            :  *
     715                 :            :  * On the client side, it is never necessary to call this method;
     716                 :            :  * although the connection needs to perform a handshake after
     717                 :            :  * connecting, #GDtlsConnection will handle this for you automatically
     718                 :            :  * when you try to send or receive data on the connection. You can call
     719                 :            :  * g_dtls_connection_handshake() manually if you want to know whether
     720                 :            :  * the initial handshake succeeded or failed (as opposed to just
     721                 :            :  * immediately trying to use @conn to read or write, in which case,
     722                 :            :  * if it fails, it may not be possible to tell if it failed before
     723                 :            :  * or after completing the handshake), but beware that servers may reject
     724                 :            :  * client authentication after the handshake has completed, so a
     725                 :            :  * successful handshake does not indicate the connection will be usable.
     726                 :            :  *
     727                 :            :  * Likewise, on the server side, although a handshake is necessary at
     728                 :            :  * the beginning of the communication, you do not need to call this
     729                 :            :  * function explicitly unless you want clearer error reporting.
     730                 :            :  *
     731                 :            :  * Previously, calling g_dtls_connection_handshake() after the initial
     732                 :            :  * handshake would trigger a rehandshake; however, this usage was
     733                 :            :  * deprecated in GLib 2.60 because rehandshaking was removed from the
     734                 :            :  * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
     735                 :            :  * the initial handshake will no longer do anything.
     736                 :            :  *
     737                 :            :  * #GDtlsConnection::accept_certificate may be emitted during the
     738                 :            :  * handshake.
     739                 :            :  *
     740                 :            :  * Returns: success or failure
     741                 :            :  *
     742                 :            :  * Since: 2.48
     743                 :            :  */
     744                 :            : gboolean
     745                 :          0 : g_dtls_connection_handshake (GDtlsConnection  *conn,
     746                 :            :                              GCancellable     *cancellable,
     747                 :            :                              GError          **error)
     748                 :            : {
     749                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
     750                 :            : 
     751                 :          0 :   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake (conn, cancellable,
     752                 :            :                                                             error);
     753                 :            : }
     754                 :            : 
     755                 :            : /**
     756                 :            :  * g_dtls_connection_handshake_async:
     757                 :            :  * @conn: a #GDtlsConnection
     758                 :            :  * @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the request
     759                 :            :  * @cancellable: (nullable): a #GCancellable, or %NULL
     760                 :            :  * @callback: callback to call when the handshake is complete
     761                 :            :  * @user_data: the data to pass to the callback function
     762                 :            :  *
     763                 :            :  * Asynchronously performs a TLS handshake on @conn. See
     764                 :            :  * g_dtls_connection_handshake() for more information.
     765                 :            :  *
     766                 :            :  * Since: 2.48
     767                 :            :  */
     768                 :            : void
     769                 :          0 : g_dtls_connection_handshake_async (GDtlsConnection      *conn,
     770                 :            :                                    int                   io_priority,
     771                 :            :                                    GCancellable         *cancellable,
     772                 :            :                                    GAsyncReadyCallback   callback,
     773                 :            :                                    gpointer              user_data)
     774                 :            : {
     775                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     776                 :            : 
     777                 :          0 :   G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake_async (conn, io_priority,
     778                 :            :                                                            cancellable,
     779                 :            :                                                            callback, user_data);
     780                 :            : }
     781                 :            : 
     782                 :            : /**
     783                 :            :  * g_dtls_connection_handshake_finish:
     784                 :            :  * @conn: a #GDtlsConnection
     785                 :            :  * @result: a #GAsyncResult.
     786                 :            :  * @error: a #GError pointer, or %NULL
     787                 :            :  *
     788                 :            :  * Finish an asynchronous TLS handshake operation. See
     789                 :            :  * g_dtls_connection_handshake() for more information.
     790                 :            :  *
     791                 :            :  * Returns: %TRUE on success, %FALSE on failure, in which
     792                 :            :  * case @error will be set.
     793                 :            :  *
     794                 :            :  * Since: 2.48
     795                 :            :  */
     796                 :            : gboolean
     797                 :          0 : g_dtls_connection_handshake_finish (GDtlsConnection  *conn,
     798                 :            :                                     GAsyncResult     *result,
     799                 :            :                                     GError          **error)
     800                 :            : {
     801                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
     802                 :            : 
     803                 :          0 :   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake_finish (conn,
     804                 :            :                                                                    result,
     805                 :            :                                                                    error);
     806                 :            : }
     807                 :            : 
     808                 :            : /**
     809                 :            :  * g_dtls_connection_shutdown:
     810                 :            :  * @conn: a #GDtlsConnection
     811                 :            :  * @shutdown_read: %TRUE to stop reception of incoming datagrams
     812                 :            :  * @shutdown_write: %TRUE to stop sending outgoing datagrams
     813                 :            :  * @cancellable: (nullable): a #GCancellable, or %NULL
     814                 :            :  * @error: a #GError, or %NULL
     815                 :            :  *
     816                 :            :  * Shut down part or all of a DTLS connection.
     817                 :            :  *
     818                 :            :  * If @shutdown_read is %TRUE then the receiving side of the connection is shut
     819                 :            :  * down, and further reading is disallowed. Subsequent calls to
     820                 :            :  * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
     821                 :            :  *
     822                 :            :  * If @shutdown_write is %TRUE then the sending side of the connection is shut
     823                 :            :  * down, and further writing is disallowed. Subsequent calls to
     824                 :            :  * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
     825                 :            :  *
     826                 :            :  * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
     827                 :            :  * is equivalent to calling g_dtls_connection_close().
     828                 :            :  *
     829                 :            :  * If @cancellable is cancelled, the #GDtlsConnection may be left
     830                 :            :  * partially-closed and any pending untransmitted data may be lost. Call
     831                 :            :  * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
     832                 :            :  *
     833                 :            :  * Returns: %TRUE on success, %FALSE otherwise
     834                 :            :  *
     835                 :            :  * Since: 2.48
     836                 :            :  */
     837                 :            : gboolean
     838                 :          0 : g_dtls_connection_shutdown (GDtlsConnection  *conn,
     839                 :            :                             gboolean          shutdown_read,
     840                 :            :                             gboolean          shutdown_write,
     841                 :            :                             GCancellable     *cancellable,
     842                 :            :                             GError          **error)
     843                 :            : {
     844                 :            :   GDtlsConnectionInterface *iface;
     845                 :            : 
     846                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
     847                 :          0 :   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
     848                 :            :                         FALSE);
     849                 :          0 :   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
     850                 :            : 
     851   [ #  #  #  # ]:          0 :   if (!shutdown_read && !shutdown_write)
     852                 :          0 :     return TRUE;
     853                 :            : 
     854                 :          0 :   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
     855                 :          0 :   g_assert (iface->shutdown != NULL);
     856                 :            : 
     857                 :          0 :   return iface->shutdown (conn, shutdown_read, shutdown_write,
     858                 :            :                           cancellable, error);
     859                 :            : }
     860                 :            : 
     861                 :            : /**
     862                 :            :  * g_dtls_connection_shutdown_async:
     863                 :            :  * @conn: a #GDtlsConnection
     864                 :            :  * @shutdown_read: %TRUE to stop reception of incoming datagrams
     865                 :            :  * @shutdown_write: %TRUE to stop sending outgoing datagrams
     866                 :            :  * @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the request
     867                 :            :  * @cancellable: (nullable): a #GCancellable, or %NULL
     868                 :            :  * @callback: callback to call when the shutdown operation is complete
     869                 :            :  * @user_data: the data to pass to the callback function
     870                 :            :  *
     871                 :            :  * Asynchronously shut down part or all of the DTLS connection. See
     872                 :            :  * g_dtls_connection_shutdown() for more information.
     873                 :            :  *
     874                 :            :  * Since: 2.48
     875                 :            :  */
     876                 :            : void
     877                 :          0 : g_dtls_connection_shutdown_async (GDtlsConnection      *conn,
     878                 :            :                                   gboolean              shutdown_read,
     879                 :            :                                   gboolean              shutdown_write,
     880                 :            :                                   int                   io_priority,
     881                 :            :                                   GCancellable         *cancellable,
     882                 :            :                                   GAsyncReadyCallback   callback,
     883                 :            :                                   gpointer              user_data)
     884                 :            : {
     885                 :            :   GDtlsConnectionInterface *iface;
     886                 :            : 
     887                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     888                 :          0 :   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
     889                 :            : 
     890                 :          0 :   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
     891                 :          0 :   g_assert (iface->shutdown_async != NULL);
     892                 :            : 
     893                 :          0 :   iface->shutdown_async (conn, TRUE, TRUE, io_priority, cancellable,
     894                 :            :                          callback, user_data);
     895                 :            : }
     896                 :            : 
     897                 :            : /**
     898                 :            :  * g_dtls_connection_shutdown_finish:
     899                 :            :  * @conn: a #GDtlsConnection
     900                 :            :  * @result: a #GAsyncResult
     901                 :            :  * @error: a #GError pointer, or %NULL
     902                 :            :  *
     903                 :            :  * Finish an asynchronous TLS shutdown operation. See
     904                 :            :  * g_dtls_connection_shutdown() for more information.
     905                 :            :  *
     906                 :            :  * Returns: %TRUE on success, %FALSE on failure, in which
     907                 :            :  * case @error will be set
     908                 :            :  *
     909                 :            :  * Since: 2.48
     910                 :            :  */
     911                 :            : gboolean
     912                 :          0 : g_dtls_connection_shutdown_finish (GDtlsConnection  *conn,
     913                 :            :                                    GAsyncResult     *result,
     914                 :            :                                    GError          **error)
     915                 :            : {
     916                 :            :   GDtlsConnectionInterface *iface;
     917                 :            : 
     918                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
     919                 :          0 :   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
     920                 :            : 
     921                 :          0 :   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
     922                 :          0 :   g_assert (iface->shutdown_finish != NULL);
     923                 :            : 
     924                 :          0 :   return iface->shutdown_finish (conn, result, error);
     925                 :            : }
     926                 :            : 
     927                 :            : /**
     928                 :            :  * g_dtls_connection_close:
     929                 :            :  * @conn: a #GDtlsConnection
     930                 :            :  * @cancellable: (nullable): a #GCancellable, or %NULL
     931                 :            :  * @error: a #GError, or %NULL
     932                 :            :  *
     933                 :            :  * Close the DTLS connection. This is equivalent to calling
     934                 :            :  * g_dtls_connection_shutdown() to shut down both sides of the connection.
     935                 :            :  *
     936                 :            :  * Closing a #GDtlsConnection waits for all buffered but untransmitted data to
     937                 :            :  * be sent before it completes. It then sends a `close_notify` DTLS alert to the
     938                 :            :  * peer and may wait for a `close_notify` to be received from the peer. It does
     939                 :            :  * not close the underlying #GDtlsConnection:base-socket; that must be closed
     940                 :            :  * separately.
     941                 :            :  *
     942                 :            :  * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED.
     943                 :            :  * Closing a #GDtlsConnection multiple times will not return an error.
     944                 :            :  *
     945                 :            :  * #GDtlsConnections will be automatically closed when the last reference is
     946                 :            :  * dropped, but you might want to call this function to make sure resources are
     947                 :            :  * released as early as possible.
     948                 :            :  *
     949                 :            :  * If @cancellable is cancelled, the #GDtlsConnection may be left
     950                 :            :  * partially-closed and any pending untransmitted data may be lost. Call
     951                 :            :  * g_dtls_connection_close() again to complete closing the #GDtlsConnection.
     952                 :            :  *
     953                 :            :  * Returns: %TRUE on success, %FALSE otherwise
     954                 :            :  *
     955                 :            :  * Since: 2.48
     956                 :            :  */
     957                 :            : gboolean
     958                 :          0 : g_dtls_connection_close (GDtlsConnection  *conn,
     959                 :            :                          GCancellable     *cancellable,
     960                 :            :                          GError          **error)
     961                 :            : {
     962                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
     963                 :          0 :   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
     964                 :            :                         FALSE);
     965                 :          0 :   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
     966                 :            : 
     967                 :          0 :   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown (conn, TRUE, TRUE,
     968                 :            :                                                            cancellable, error);
     969                 :            : }
     970                 :            : 
     971                 :            : /**
     972                 :            :  * g_dtls_connection_close_async:
     973                 :            :  * @conn: a #GDtlsConnection
     974                 :            :  * @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the request
     975                 :            :  * @cancellable: (nullable): a #GCancellable, or %NULL
     976                 :            :  * @callback: callback to call when the close operation is complete
     977                 :            :  * @user_data: the data to pass to the callback function
     978                 :            :  *
     979                 :            :  * Asynchronously close the DTLS connection. See g_dtls_connection_close() for
     980                 :            :  * more information.
     981                 :            :  *
     982                 :            :  * Since: 2.48
     983                 :            :  */
     984                 :            : void
     985                 :          0 : g_dtls_connection_close_async (GDtlsConnection      *conn,
     986                 :            :                                int                   io_priority,
     987                 :            :                                GCancellable         *cancellable,
     988                 :            :                                GAsyncReadyCallback   callback,
     989                 :            :                                gpointer              user_data)
     990                 :            : {
     991                 :          0 :   g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
     992                 :          0 :   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
     993                 :            : 
     994                 :          0 :   G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown_async (conn, TRUE, TRUE,
     995                 :            :                                                           io_priority,
     996                 :            :                                                           cancellable,
     997                 :            :                                                           callback, user_data);
     998                 :            : }
     999                 :            : 
    1000                 :            : /**
    1001                 :            :  * g_dtls_connection_close_finish:
    1002                 :            :  * @conn: a #GDtlsConnection
    1003                 :            :  * @result: a #GAsyncResult
    1004                 :            :  * @error: a #GError pointer, or %NULL
    1005                 :            :  *
    1006                 :            :  * Finish an asynchronous TLS close operation. See g_dtls_connection_close()
    1007                 :            :  * for more information.
    1008                 :            :  *
    1009                 :            :  * Returns: %TRUE on success, %FALSE on failure, in which
    1010                 :            :  * case @error will be set
    1011                 :            :  *
    1012                 :            :  * Since: 2.48
    1013                 :            :  */
    1014                 :            : gboolean
    1015                 :          0 : g_dtls_connection_close_finish (GDtlsConnection  *conn,
    1016                 :            :                                 GAsyncResult     *result,
    1017                 :            :                                 GError          **error)
    1018                 :            : {
    1019                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
    1020                 :          0 :   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
    1021                 :            : 
    1022                 :          0 :   return G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown_finish (conn, result,
    1023                 :            :                                                                   error);
    1024                 :            : }
    1025                 :            : 
    1026                 :            : /**
    1027                 :            :  * g_dtls_connection_emit_accept_certificate:
    1028                 :            :  * @conn: a #GDtlsConnection
    1029                 :            :  * @peer_cert: the peer's #GTlsCertificate
    1030                 :            :  * @errors: the problems with @peer_cert
    1031                 :            :  *
    1032                 :            :  * Used by #GDtlsConnection implementations to emit the
    1033                 :            :  * #GDtlsConnection::accept-certificate signal.
    1034                 :            :  *
    1035                 :            :  * Returns: %TRUE if one of the signal handlers has returned
    1036                 :            :  *     %TRUE to accept @peer_cert
    1037                 :            :  *
    1038                 :            :  * Since: 2.48
    1039                 :            :  */
    1040                 :            : gboolean
    1041                 :          0 : g_dtls_connection_emit_accept_certificate (GDtlsConnection      *conn,
    1042                 :            :                                            GTlsCertificate      *peer_cert,
    1043                 :            :                                            GTlsCertificateFlags  errors)
    1044                 :            : {
    1045                 :          0 :   gboolean accept = FALSE;
    1046                 :            : 
    1047                 :          0 :   g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
    1048                 :            :                  peer_cert, errors, &accept);
    1049                 :          0 :   return accept;
    1050                 :            : }
    1051                 :            : 
    1052                 :            : /**
    1053                 :            :  * g_dtls_connection_set_advertised_protocols:
    1054                 :            :  * @conn: a #GDtlsConnection
    1055                 :            :  * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
    1056                 :            :  *   array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
    1057                 :            :  *
    1058                 :            :  * Sets the list of application-layer protocols to advertise that the
    1059                 :            :  * caller is willing to speak on this connection. The
    1060                 :            :  * Application-Layer Protocol Negotiation (ALPN) extension will be
    1061                 :            :  * used to negotiate a compatible protocol with the peer; use
    1062                 :            :  * g_dtls_connection_get_negotiated_protocol() to find the negotiated
    1063                 :            :  * protocol after the handshake.  Specifying %NULL for the the value
    1064                 :            :  * of @protocols will disable ALPN negotiation.
    1065                 :            :  *
    1066                 :            :  * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
    1067                 :            :  * for a list of registered protocol IDs.
    1068                 :            :  *
    1069                 :            :  * Since: 2.60
    1070                 :            :  */
    1071                 :            : void
    1072                 :          0 : g_dtls_connection_set_advertised_protocols (GDtlsConnection     *conn,
    1073                 :            :                                             const gchar * const *protocols)
    1074                 :            : {
    1075                 :            :   GDtlsConnectionInterface *iface;
    1076                 :            : 
    1077                 :          0 :   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
    1078         [ #  # ]:          0 :   if (iface->set_advertised_protocols == NULL)
    1079                 :          0 :     return;
    1080                 :            : 
    1081                 :          0 :   iface->set_advertised_protocols (conn, protocols);
    1082                 :            : }
    1083                 :            : 
    1084                 :            : /**
    1085                 :            :  * g_dtls_connection_get_negotiated_protocol:
    1086                 :            :  * @conn: a #GDtlsConnection
    1087                 :            :  *
    1088                 :            :  * Gets the name of the application-layer protocol negotiated during
    1089                 :            :  * the handshake.
    1090                 :            :  *
    1091                 :            :  * If the peer did not use the ALPN extension, or did not advertise a
    1092                 :            :  * protocol that matched one of @conn's protocols, or the TLS backend
    1093                 :            :  * does not support ALPN, then this will be %NULL. See
    1094                 :            :  * g_dtls_connection_set_advertised_protocols().
    1095                 :            :  *
    1096                 :            :  * Returns: (nullable): the negotiated protocol, or %NULL
    1097                 :            :  *
    1098                 :            :  * Since: 2.60
    1099                 :            :  */
    1100                 :            : const gchar *
    1101                 :          0 : g_dtls_connection_get_negotiated_protocol (GDtlsConnection *conn)
    1102                 :            : {
    1103                 :            :   GDtlsConnectionInterface *iface;
    1104                 :            : 
    1105                 :          0 :   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
    1106         [ #  # ]:          0 :   if (iface->get_negotiated_protocol == NULL)
    1107                 :          0 :     return NULL;
    1108                 :            : 
    1109                 :          0 :   return iface->get_negotiated_protocol (conn);
    1110                 :            : }
    1111                 :            : 
    1112                 :            : /**
    1113                 :            :  * g_dtls_connection_get_channel_binding_data:
    1114                 :            :  * @conn: a #GDtlsConnection
    1115                 :            :  * @type: #GTlsChannelBindingType type of data to fetch
    1116                 :            :  * @data: (out callee-allocates)(optional)(transfer none): #GByteArray is
    1117                 :            :  *        filled with the binding data, or %NULL
    1118                 :            :  * @error: a #GError pointer, or %NULL
    1119                 :            :  *
    1120                 :            :  * Query the TLS backend for TLS channel binding data of @type for @conn.
    1121                 :            :  *
    1122                 :            :  * This call retrieves TLS channel binding data as specified in RFC
    1123                 :            :  * [5056](https://tools.ietf.org/html/rfc5056), RFC
    1124                 :            :  * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs.  The
    1125                 :            :  * binding data is returned in @data.  The @data is resized by the callee
    1126                 :            :  * using #GByteArray buffer management and will be freed when the @data
    1127                 :            :  * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only
    1128                 :            :  * check whether TLS backend is able to fetch the data (e.g. whether @type
    1129                 :            :  * is supported by the TLS backend). It does not guarantee that the data
    1130                 :            :  * will be available though.  That could happen if TLS connection does not
    1131                 :            :  * support @type or the binding data is not available yet due to additional
    1132                 :            :  * negotiation or input required.
    1133                 :            :  *
    1134                 :            :  * Returns: %TRUE on success, %FALSE otherwise
    1135                 :            :  *
    1136                 :            :  * Since: 2.66
    1137                 :            :  */
    1138                 :            : gboolean
    1139                 :          2 : g_dtls_connection_get_channel_binding_data (GDtlsConnection         *conn,
    1140                 :            :                                             GTlsChannelBindingType   type,
    1141                 :            :                                             GByteArray              *data,
    1142                 :            :                                             GError                 **error)
    1143                 :            : {
    1144                 :            :   GDtlsConnectionInterface *iface;
    1145                 :            : 
    1146                 :          2 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
    1147                 :          2 :   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
    1148                 :            : 
    1149                 :          2 :   iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
    1150         [ +  - ]:          2 :   if (iface->get_binding_data == NULL)
    1151                 :            :     {
    1152                 :          2 :       g_set_error_literal (error, G_TLS_CHANNEL_BINDING_ERROR,
    1153                 :            :           G_TLS_CHANNEL_BINDING_ERROR_NOT_IMPLEMENTED,
    1154                 :            :           _("TLS backend does not implement TLS binding retrieval"));
    1155                 :          2 :       return FALSE;
    1156                 :            :     }
    1157                 :            : 
    1158                 :          0 :   return iface->get_binding_data (conn, type, data, error);
    1159                 :            : }
    1160                 :            : 
    1161                 :            : /**
    1162                 :            :  * g_dtls_connection_get_protocol_version:
    1163                 :            :  * @conn: a #GDTlsConnection
    1164                 :            :  *
    1165                 :            :  * Returns the current DTLS protocol version, which may be
    1166                 :            :  * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
    1167                 :            :  * has been closed, or if the TLS backend has implemented a protocol version
    1168                 :            :  * that is not a recognized #GTlsProtocolVersion.
    1169                 :            :  *
    1170                 :            :  * Returns: The current DTLS protocol version
    1171                 :            :  *
    1172                 :            :  * Since: 2.70
    1173                 :            :  */
    1174                 :            : GTlsProtocolVersion
    1175                 :          0 : g_dtls_connection_get_protocol_version (GDtlsConnection *conn)
    1176                 :            : {
    1177                 :            :   GTlsProtocolVersion protocol_version;
    1178                 :            :   GEnumClass *enum_class;
    1179                 :            :   GEnumValue *enum_value;
    1180                 :            : 
    1181                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), G_TLS_PROTOCOL_VERSION_UNKNOWN);
    1182                 :            : 
    1183                 :          0 :   g_object_get (G_OBJECT (conn),
    1184                 :            :                 "protocol-version", &protocol_version,
    1185                 :            :                 NULL);
    1186                 :            : 
    1187                 :            :   /* Convert unknown values to G_TLS_PROTOCOL_VERSION_UNKNOWN. */
    1188                 :          0 :   enum_class = g_type_class_peek_static (G_TYPE_TLS_PROTOCOL_VERSION);
    1189                 :          0 :   enum_value = g_enum_get_value (enum_class, protocol_version);
    1190         [ #  # ]:          0 :   return enum_value ? protocol_version : G_TLS_PROTOCOL_VERSION_UNKNOWN;
    1191                 :            : }
    1192                 :            : 
    1193                 :            : /**
    1194                 :            :  * g_dtls_connection_get_ciphersuite_name:
    1195                 :            :  * @conn: a #GDTlsConnection
    1196                 :            :  *
    1197                 :            :  * Returns the name of the current DTLS ciphersuite, or %NULL if the
    1198                 :            :  * connection has not handshaked or has been closed. Beware that the TLS
    1199                 :            :  * backend may use any of multiple different naming conventions, because
    1200                 :            :  * OpenSSL and GnuTLS have their own ciphersuite naming conventions that
    1201                 :            :  * are different from each other and different from the standard, IANA-
    1202                 :            :  * registered ciphersuite names. The ciphersuite name is intended to be
    1203                 :            :  * displayed to the user for informative purposes only, and parsing it
    1204                 :            :  * is not recommended.
    1205                 :            :  *
    1206                 :            :  * Returns: (nullable): The name of the current DTLS ciphersuite, or %NULL
    1207                 :            :  *
    1208                 :            :  * Since: 2.70
    1209                 :            :  */
    1210                 :            : gchar *
    1211                 :          0 : g_dtls_connection_get_ciphersuite_name (GDtlsConnection *conn)
    1212                 :            : {
    1213                 :            :   gchar *ciphersuite_name;
    1214                 :            : 
    1215                 :          0 :   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
    1216                 :            : 
    1217                 :          0 :   g_object_get (G_OBJECT (conn),
    1218                 :            :                 "ciphersuite-name", &ciphersuite_name,
    1219                 :            :                 NULL);
    1220                 :            : 
    1221                 :          0 :   return g_steal_pointer (&ciphersuite_name);
    1222                 :            : }

Generated by: LCOV version 1.14