Coverage Report

Created: 2025-07-23 08:13

/src/pango/subprojects/glib/gio/gdtlsconnection.c
Line
Count
Source (jump to first uncovered line)
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
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
g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
89
0
{
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
0
  g_object_interface_install_property (iface,
99
0
                                       g_param_spec_object ("base-socket", NULL, NULL,
100
0
                                                            G_TYPE_DATAGRAM_BASED,
101
0
                                                            G_PARAM_READWRITE |
102
0
                                                            G_PARAM_CONSTRUCT_ONLY |
103
0
                                                            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
0
  g_object_interface_install_property (iface,
127
0
                                       g_param_spec_object ("database", NULL, NULL,
128
0
                                                            G_TYPE_TLS_DATABASE,
129
0
                                                            G_PARAM_READWRITE |
130
0
                                                            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
0
  g_object_interface_install_property (iface,
141
0
                                       g_param_spec_object ("interaction", NULL, NULL,
142
0
                                                            G_TYPE_TLS_INTERACTION,
143
0
                                                            G_PARAM_READWRITE |
144
0
                                                            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
0
  g_object_interface_install_property (iface,
154
0
                                       g_param_spec_boolean ("require-close-notify", NULL, NULL,
155
0
                                                             TRUE,
156
0
                                                             G_PARAM_READWRITE |
157
0
                                                             G_PARAM_CONSTRUCT |
158
0
                                                             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
0
  g_object_interface_install_property (iface,
170
0
                                       g_param_spec_enum ("rehandshake-mode", NULL, NULL,
171
0
                                                          G_TYPE_TLS_REHANDSHAKE_MODE,
172
0
                                                          G_TLS_REHANDSHAKE_NEVER,
173
0
                                                          G_PARAM_READWRITE |
174
0
                                                          G_PARAM_CONSTRUCT |
175
0
                                                          G_PARAM_STATIC_STRINGS |
176
0
                                                          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
0
  g_object_interface_install_property (iface,
186
0
                                       g_param_spec_object ("certificate", NULL, NULL,
187
0
                                                            G_TYPE_TLS_CERTIFICATE,
188
0
                                                            G_PARAM_READWRITE |
189
0
                                                            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
0
  g_object_interface_install_property (iface,
203
0
                                       g_param_spec_object ("peer-certificate", NULL, NULL,
204
0
                                                            G_TYPE_TLS_CERTIFICATE,
205
0
                                                            G_PARAM_READABLE |
206
0
                                                            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
0
  g_object_interface_install_property (iface,
228
0
                                       g_param_spec_flags ("peer-certificate-errors", NULL, NULL,
229
0
                                                           G_TYPE_TLS_CERTIFICATE_FLAGS,
230
0
                                                           0,
231
0
                                                           G_PARAM_READABLE |
232
0
                                                           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
0
  g_object_interface_install_property (iface,
243
0
                                       g_param_spec_boxed ("advertised-protocols", NULL, NULL,
244
0
                                                           G_TYPE_STRV,
245
0
                                                           G_PARAM_READWRITE |
246
0
                                                           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
0
  g_object_interface_install_property (iface,
256
0
                                       g_param_spec_string ("negotiated-protocol", NULL, NULL,
257
0
                                                            NULL,
258
0
                                                            G_PARAM_READABLE |
259
0
                                                            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
0
  g_object_interface_install_property (iface,
269
0
                                       g_param_spec_enum ("protocol-version", NULL, NULL,
270
0
                                                          G_TYPE_TLS_PROTOCOL_VERSION,
271
0
                                                          G_TLS_PROTOCOL_VERSION_UNKNOWN,
272
0
                                                          G_PARAM_READABLE |
273
0
                                                          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
0
  g_object_interface_install_property (iface,
283
0
                                       g_param_spec_string ("ciphersuite-name", NULL, NULL,
284
0
                                                            NULL,
285
0
                                                            G_PARAM_READABLE |
286
0
                                                            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
0
  signals[ACCEPT_CERTIFICATE] =
345
0
    g_signal_new (I_("accept-certificate"),
346
0
                  G_TYPE_DTLS_CONNECTION,
347
0
                  G_SIGNAL_RUN_LAST,
348
0
                  G_STRUCT_OFFSET (GDtlsConnectionInterface, accept_certificate),
349
0
                  g_signal_accumulator_true_handled, NULL,
350
0
                  _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGS,
351
0
                  G_TYPE_BOOLEAN, 2,
352
0
                  G_TYPE_TLS_CERTIFICATE,
353
0
                  G_TYPE_TLS_CERTIFICATE_FLAGS);
354
0
  g_signal_set_va_marshaller (signals[ACCEPT_CERTIFICATE],
355
0
                              G_TYPE_FROM_INTERFACE (iface),
356
0
                              _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGSv);
357
0
}
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
g_dtls_connection_set_database (GDtlsConnection *conn,
380
                                GTlsDatabase    *database)
381
0
{
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
0
                "database", database,
387
0
                NULL);
388
0
}
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
g_dtls_connection_get_database (GDtlsConnection *conn)
403
0
{
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
0
                "database", &database,
410
0
                NULL);
411
0
  if (database)
412
0
    g_object_unref (database);
413
0
  return database;
414
0
}
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
g_dtls_connection_set_certificate (GDtlsConnection *conn,
444
                                   GTlsCertificate *certificate)
445
0
{
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
0
}
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
g_dtls_connection_get_certificate (GDtlsConnection *conn)
465
0
{
466
0
  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
0
}
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
g_dtls_connection_set_interaction (GDtlsConnection *conn,
493
                                   GTlsInteraction *interaction)
494
0
{
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
0
}
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
g_dtls_connection_get_interaction (GDtlsConnection       *conn)
515
0
{
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
0
}
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
g_dtls_connection_get_peer_certificate (GDtlsConnection *conn)
541
0
{
542
0
  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
0
}
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
g_dtls_connection_get_peer_certificate_errors (GDtlsConnection *conn)
567
0
{
568
0
  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
0
}
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
g_dtls_connection_set_require_close_notify (GDtlsConnection *conn,
611
                                            gboolean         require_close_notify)
612
0
{
613
0
  g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
614
615
0
  g_object_set (G_OBJECT (conn),
616
0
                "require-close-notify", require_close_notify,
617
0
                NULL);
618
0
}
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
g_dtls_connection_get_require_close_notify (GDtlsConnection *conn)
634
0
{
635
0
  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
0
                "require-close-notify", &require_close_notify,
641
0
                NULL);
642
0
  return require_close_notify;
643
0
}
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
g_dtls_connection_set_rehandshake_mode (GDtlsConnection     *conn,
664
                                        GTlsRehandshakeMode  mode)
665
0
{
666
0
  g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
667
668
0
  g_object_set (G_OBJECT (conn),
669
0
                "rehandshake-mode", G_TLS_REHANDSHAKE_SAFELY,
670
0
                NULL);
671
0
}
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
g_dtls_connection_get_rehandshake_mode (GDtlsConnection *conn)
692
0
{
693
0
  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
0
                "rehandshake-mode", &mode,
702
0
                NULL);
703
0
  return G_TLS_REHANDSHAKE_SAFELY;
704
0
}
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
g_dtls_connection_handshake (GDtlsConnection  *conn,
746
                             GCancellable     *cancellable,
747
                             GError          **error)
748
0
{
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
0
                                                            error);
753
0
}
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
g_dtls_connection_handshake_async (GDtlsConnection      *conn,
770
                                   int                   io_priority,
771
                                   GCancellable         *cancellable,
772
                                   GAsyncReadyCallback   callback,
773
                                   gpointer              user_data)
774
0
{
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
0
                                                           cancellable,
779
0
                                                           callback, user_data);
780
0
}
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
g_dtls_connection_handshake_finish (GDtlsConnection  *conn,
798
                                    GAsyncResult     *result,
799
                                    GError          **error)
800
0
{
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
0
                                                                   result,
805
0
                                                                   error);
806
0
}
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
g_dtls_connection_shutdown (GDtlsConnection  *conn,
839
                            gboolean          shutdown_read,
840
                            gboolean          shutdown_write,
841
                            GCancellable     *cancellable,
842
                            GError          **error)
843
0
{
844
0
  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
0
                        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
0
                          cancellable, error);
859
0
}
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
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
0
{
885
0
  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
0
                         callback, user_data);
895
0
}
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
g_dtls_connection_shutdown_finish (GDtlsConnection  *conn,
913
                                   GAsyncResult     *result,
914
                                   GError          **error)
915
0
{
916
0
  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
0
}
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
g_dtls_connection_close (GDtlsConnection  *conn,
959
                         GCancellable     *cancellable,
960
                         GError          **error)
961
0
{
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
0
                        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
0
                                                           cancellable, error);
969
0
}
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
g_dtls_connection_close_async (GDtlsConnection      *conn,
986
                               int                   io_priority,
987
                               GCancellable         *cancellable,
988
                               GAsyncReadyCallback   callback,
989
                               gpointer              user_data)
990
0
{
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
0
                                                          io_priority,
996
0
                                                          cancellable,
997
0
                                                          callback, user_data);
998
0
}
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
g_dtls_connection_close_finish (GDtlsConnection  *conn,
1016
                                GAsyncResult     *result,
1017
                                GError          **error)
1018
0
{
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
0
                                                                  error);
1024
0
}
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
g_dtls_connection_emit_accept_certificate (GDtlsConnection      *conn,
1042
                                           GTlsCertificate      *peer_cert,
1043
                                           GTlsCertificateFlags  errors)
1044
0
{
1045
0
  gboolean accept = FALSE;
1046
1047
0
  g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
1048
0
                 peer_cert, errors, &accept);
1049
0
  return accept;
1050
0
}
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
g_dtls_connection_set_advertised_protocols (GDtlsConnection     *conn,
1073
                                            const gchar * const *protocols)
1074
0
{
1075
0
  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
0
}
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
g_dtls_connection_get_negotiated_protocol (GDtlsConnection *conn)
1102
0
{
1103
0
  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
0
}
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 caller-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
g_dtls_connection_get_channel_binding_data (GDtlsConnection         *conn,
1140
                                            GTlsChannelBindingType   type,
1141
                                            GByteArray              *data,
1142
                                            GError                 **error)
1143
0
{
1144
0
  GDtlsConnectionInterface *iface;
1145
1146
0
  g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
1147
0
  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1148
1149
0
  iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
1150
0
  if (iface->get_binding_data == NULL)
1151
0
    {
1152
0
      g_set_error_literal (error, G_TLS_CHANNEL_BINDING_ERROR,
1153
0
          G_TLS_CHANNEL_BINDING_ERROR_NOT_IMPLEMENTED,
1154
0
          _("TLS backend does not implement TLS binding retrieval"));
1155
0
      return FALSE;
1156
0
    }
1157
1158
0
  return iface->get_binding_data (conn, type, data, error);
1159
0
}
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
g_dtls_connection_get_protocol_version (GDtlsConnection *conn)
1176
0
{
1177
0
  GTlsProtocolVersion protocol_version;
1178
0
  GEnumClass *enum_class;
1179
0
  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
0
                "protocol-version", &protocol_version,
1185
0
                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
0
}
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
g_dtls_connection_get_ciphersuite_name (GDtlsConnection *conn)
1212
0
{
1213
0
  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
0
                "ciphersuite-name", &ciphersuite_name,
1219
0
                NULL);
1220
1221
0
  return g_steal_pointer (&ciphersuite_name);
1222
0
}