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 {
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 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 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 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 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 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 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 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 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 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 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 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 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 signals[ACCEPT_CERTIFICATE] =
345 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 g_signal_set_va_marshaller (signals[ACCEPT_CERTIFICATE],
355 G_TYPE_FROM_INTERFACE (iface),
356 _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGSv);
357 }
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 {
382 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
383 g_return_if_fail (database == NULL || G_IS_TLS_DATABASE (database));
384
385 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 g_dtls_connection_get_database (GDtlsConnection *conn)
403 {
404 GTlsDatabase *database = NULL;
405
406 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
407
408 g_object_get (G_OBJECT (conn),
409 "database", &database,
410 NULL);
411 if (database)
412 g_object_unref (database);
413 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 g_dtls_connection_set_certificate (GDtlsConnection *conn,
444 GTlsCertificate *certificate)
445 {
446 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
447 g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
448
449 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 g_dtls_connection_get_certificate (GDtlsConnection *conn)
465 {
466 GTlsCertificate *certificate;
467
468 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
469
470 g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
471 if (certificate)
472 g_object_unref (certificate);
473
474 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 g_dtls_connection_set_interaction (GDtlsConnection *conn,
493 GTlsInteraction *interaction)
494 {
495 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
496 g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
497
498 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 g_dtls_connection_get_interaction (GDtlsConnection *conn)
515 {
516 GTlsInteraction *interaction = NULL;
517
518 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
519
520 g_object_get (G_OBJECT (conn), "interaction", &interaction, NULL);
521 if (interaction)
522 g_object_unref (interaction);
523
524 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 g_dtls_connection_get_peer_certificate (GDtlsConnection *conn)
541 {
542 GTlsCertificate *peer_certificate;
543
544 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
545
546 g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
547 if (peer_certificate)
548 g_object_unref (peer_certificate);
549
550 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 g_dtls_connection_get_peer_certificate_errors (GDtlsConnection *conn)
567 {
568 GTlsCertificateFlags errors;
569
570 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), 0);
571
572 g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
573 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 g_dtls_connection_set_require_close_notify (GDtlsConnection *conn,
611 gboolean require_close_notify)
612 {
613 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
614
615 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 g_dtls_connection_get_require_close_notify (GDtlsConnection *conn)
634 {
635 gboolean require_close_notify;
636
637 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), TRUE);
638
639 g_object_get (G_OBJECT (conn),
640 "require-close-notify", &require_close_notify,
641 NULL);
642 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 g_dtls_connection_set_rehandshake_mode (GDtlsConnection *conn,
664 GTlsRehandshakeMode mode)
665 {
666 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
667
668 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 g_dtls_connection_get_rehandshake_mode (GDtlsConnection *conn)
692 {
693 GTlsRehandshakeMode mode;
694
695 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 g_object_get (G_OBJECT (conn),
701 "rehandshake-mode", &mode,
702 NULL);
703 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 g_dtls_connection_handshake (GDtlsConnection *conn,
746 GCancellable *cancellable,
747 GError **error)
748 {
749 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
750
751 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][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 {
775 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
776
777 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 g_dtls_connection_handshake_finish (GDtlsConnection *conn,
798 GAsyncResult *result,
799 GError **error)
800 {
801 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
802
803 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 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 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
847 g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
848 FALSE);
849 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
850
851 if (!shutdown_read && !shutdown_write)
852 return TRUE;
853
854 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
855 g_assert (iface->shutdown != NULL);
856
857 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][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 {
885 GDtlsConnectionInterface *iface;
886
887 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
888 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
889
890 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
891 g_assert (iface->shutdown_async != NULL);
892
893 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 g_dtls_connection_shutdown_finish (GDtlsConnection *conn,
913 GAsyncResult *result,
914 GError **error)
915 {
916 GDtlsConnectionInterface *iface;
917
918 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
919 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
920
921 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
922 g_assert (iface->shutdown_finish != NULL);
923
924 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 g_dtls_connection_close (GDtlsConnection *conn,
959 GCancellable *cancellable,
960 GError **error)
961 {
962 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
963 g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
964 FALSE);
965 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
966
967 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][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 {
991 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
992 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
993
994 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 g_dtls_connection_close_finish (GDtlsConnection *conn,
1016 GAsyncResult *result,
1017 GError **error)
1018 {
1019 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
1020 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1021
1022 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 g_dtls_connection_emit_accept_certificate (GDtlsConnection *conn,
1042 GTlsCertificate *peer_cert,
1043 GTlsCertificateFlags errors)
1044 {
1045 gboolean accept = FALSE;
1046
1047 g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
1048 peer_cert, errors, &accept);
1049 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 g_dtls_connection_set_advertised_protocols (GDtlsConnection *conn,
1073 const gchar * const *protocols)
1074 {
1075 GDtlsConnectionInterface *iface;
1076
1077 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
1078 if (iface->set_advertised_protocols == NULL)
1079 return;
1080
1081 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 g_dtls_connection_get_negotiated_protocol (GDtlsConnection *conn)
1102 {
1103 GDtlsConnectionInterface *iface;
1104
1105 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
1106 if (iface->get_negotiated_protocol == NULL)
1107 return NULL;
1108
1109 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 g_dtls_connection_get_channel_binding_data (GDtlsConnection *conn,
1140 GTlsChannelBindingType type,
1141 GByteArray *data,
1142 GError **error)
1143 {
1144 GDtlsConnectionInterface *iface;
1145
1146 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
1147 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1148
1149 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
1150 if (iface->get_binding_data == NULL)
1151 {
1152 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 return FALSE;
1156 }
1157
1158 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 g_dtls_connection_get_protocol_version (GDtlsConnection *conn)
1176 {
1177 GTlsProtocolVersion protocol_version;
1178 GEnumClass *enum_class;
1179 GEnumValue *enum_value;
1180
1181 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), G_TLS_PROTOCOL_VERSION_UNKNOWN);
1182
1183 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 enum_class = g_type_class_peek_static (G_TYPE_TLS_PROTOCOL_VERSION);
1189 enum_value = g_enum_get_value (enum_class, protocol_version);
1190 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 g_dtls_connection_get_ciphersuite_name (GDtlsConnection *conn)
1212 {
1213 gchar *ciphersuite_name;
1214
1215 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
1216
1217 g_object_get (G_OBJECT (conn),
1218 "ciphersuite-name", &ciphersuite_name,
1219 NULL);
1220
1221 return g_steal_pointer (&ciphersuite_name);
1222 }