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