nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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 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 "gdtlsclientconnection.h"
30 #include "gtlsdatabase.h"
31 #include "gtlsinteraction.h"
32 #include "glibintl.h"
33  
34 /**
35 * SECTION:gdtlsconnection
36 * @short_description: DTLS connection type
37 * @include: gio/gio.h
38 *
39 * #GDtlsConnection is the base DTLS connection class type, which wraps
40 * a #GDatagramBased and provides DTLS encryption on top of it. Its
41 * subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
42 * implement client-side and server-side DTLS, respectively.
43 *
44 * For TLS support, see #GTlsConnection.
45 *
46 * As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
47 * presenting a datagram-socket-like API for the encrypted connection. This
48 * operates over a base datagram connection, which is also a #GDatagramBased
49 * (#GDtlsConnection:base-socket).
50 *
51 * To close a DTLS connection, use g_dtls_connection_close().
52 *
53 * Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
54 * on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
55 * do that if they wish. If they do not, and g_socket_close() is called on the
56 * base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
57 * error on further I/O.
58 *
59 * Since: 2.48
60 */
61  
62 /**
63 * GDtlsConnection:
64 *
65 * Abstract base class for the backend-specific #GDtlsClientConnection
66 * and #GDtlsServerConnection types.
67 *
68 * Since: 2.48
69 */
70  
71 G_DEFINE_INTERFACE (GDtlsConnection, g_dtls_connection, G_TYPE_DATAGRAM_BASED);
72  
73 enum {
74 ACCEPT_CERTIFICATE,
75 LAST_SIGNAL
76 };
77  
78 static guint signals[LAST_SIGNAL] = { 0 };
79  
80 enum {
81 PROP_BASE_SOCKET = 1,
82 PROP_REQUIRE_CLOSE_NOTIFY,
83 PROP_REHANDSHAKE_MODE,
84 PROP_DATABASE,
85 PROP_INTERACTION,
86 PROP_CERTIFICATE,
87 PROP_PEER_CERTIFICATE,
88 PROP_PEER_CERTIFICATE_ERRORS,
89 };
90  
91 static void
92 g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
93 {
94 /**
95 * GDtlsConnection:base-socket:
96 *
97 * The #GDatagramBased that the connection wraps. Note that this may be any
98 * implementation of #GDatagramBased, not just a #GSocket.
99 *
100 * Since: 2.48
101 */
102 g_object_interface_install_property (iface,
103 g_param_spec_object ("base-socket",
104 P_("Base Socket"),
105 P_("The GDatagramBased that the connection wraps"),
106 G_TYPE_DATAGRAM_BASED,
107 G_PARAM_READWRITE |
108 G_PARAM_CONSTRUCT_ONLY |
109 G_PARAM_STATIC_STRINGS));
110 /**
111 * GDtlsConnection:database:
112 *
113 * The certificate database to use when verifying this TLS connection.
114 * If no certificate database is set, then the default database will be
115 * used. See g_dtls_backend_get_default_database().
116 *
117 * Since: 2.48
118 */
119 g_object_interface_install_property (iface,
120 g_param_spec_object ("database",
121 P_("Database"),
122 P_("Certificate database to use for looking up or verifying certificates"),
123 G_TYPE_TLS_DATABASE,
124 G_PARAM_READWRITE |
125 G_PARAM_STATIC_STRINGS));
126 /**
127 * GDtlsConnection:interaction:
128 *
129 * A #GTlsInteraction object to be used when the connection or certificate
130 * database need to interact with the user. This will be used to prompt the
131 * user for passwords where necessary.
132 *
133 * Since: 2.48
134 */
135 g_object_interface_install_property (iface,
136 g_param_spec_object ("interaction",
137 P_("Interaction"),
138 P_("Optional object for user interaction"),
139 G_TYPE_TLS_INTERACTION,
140 G_PARAM_READWRITE |
141 G_PARAM_STATIC_STRINGS));
142 /**
143 * GDtlsConnection:require-close-notify:
144 *
145 * Whether or not proper TLS close notification is required.
146 * See g_dtls_connection_set_require_close_notify().
147 *
148 * Since: 2.48
149 */
150 g_object_interface_install_property (iface,
151 g_param_spec_boolean ("require-close-notify",
152 P_("Require close notify"),
153 P_("Whether to require proper TLS close notification"),
154 TRUE,
155 G_PARAM_READWRITE |
156 G_PARAM_CONSTRUCT |
157 G_PARAM_STATIC_STRINGS));
158 /**
159 * GDtlsConnection:rehandshake-mode:
160 *
161 * The rehandshaking mode. See
162 * g_dtls_connection_set_rehandshake_mode().
163 *
164 * Since: 2.48
165 */
166 g_object_interface_install_property (iface,
167 g_param_spec_enum ("rehandshake-mode",
168 P_("Rehandshake mode"),
169 P_("When to allow rehandshaking"),
170 G_TYPE_TLS_REHANDSHAKE_MODE,
171 G_TLS_REHANDSHAKE_NEVER,
172 G_PARAM_READWRITE |
173 G_PARAM_CONSTRUCT |
174 G_PARAM_STATIC_STRINGS));
175 /**
176 * GDtlsConnection:certificate:
177 *
178 * The connection's certificate; see
179 * g_dtls_connection_set_certificate().
180 *
181 * Since: 2.48
182 */
183 g_object_interface_install_property (iface,
184 g_param_spec_object ("certificate",
185 P_("Certificate"),
186 P_("The connection's certificate"),
187 G_TYPE_TLS_CERTIFICATE,
188 G_PARAM_READWRITE |
189 G_PARAM_STATIC_STRINGS));
190 /**
191 * GDtlsConnection:peer-certificate:
192 *
193 * The connection's peer's certificate, after the TLS handshake has
194 * completed and the certificate has been accepted. Note in
195 * particular that this is not yet set during the emission of
196 * #GDtlsConnection::accept-certificate.
197 *
198 * (You can watch for a #GObject::notify signal on this property to
199 * detect when a handshake has occurred.)
200 *
201 * Since: 2.48
202 */
203 g_object_interface_install_property (iface,
204 g_param_spec_object ("peer-certificate",
205 P_("Peer Certificate"),
206 P_("The connection's peer's certificate"),
207 G_TYPE_TLS_CERTIFICATE,
208 G_PARAM_READABLE |
209 G_PARAM_STATIC_STRINGS));
210 /**
211 * GDtlsConnection:peer-certificate-errors:
212 *
213 * The errors noticed-and-ignored while verifying
214 * #GDtlsConnection:peer-certificate. Normally this should be 0, but
215 * it may not be if #GDtlsClientConnection:validation-flags is not
216 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
217 * #GDtlsConnection::accept-certificate overrode the default
218 * behavior.
219 *
220 * Since: 2.48
221 */
222 g_object_interface_install_property (iface,
223 g_param_spec_flags ("peer-certificate-errors",
224 P_("Peer Certificate Errors"),
225 P_("Errors found with the peer's certificate"),
226 G_TYPE_TLS_CERTIFICATE_FLAGS,
227 0,
228 G_PARAM_READABLE |
229 G_PARAM_STATIC_STRINGS));
230  
231 /**
232 * GDtlsConnection::accept-certificate:
233 * @conn: a #GDtlsConnection
234 * @peer_cert: the peer's #GTlsCertificate
235 * @errors: the problems with @peer_cert.
236 *
237 * Emitted during the TLS handshake after the peer certificate has
238 * been received. You can examine @peer_cert's certification path by
239 * calling g_tls_certificate_get_issuer() on it.
240 *
241 * For a client-side connection, @peer_cert is the server's
242 * certificate, and the signal will only be emitted if the
243 * certificate was not acceptable according to @conn's
244 * #GDtlsClientConnection:validation_flags. If you would like the
245 * certificate to be accepted despite @errors, return %TRUE from the
246 * signal handler. Otherwise, if no handler accepts the certificate,
247 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
248 *
249 * For a server-side connection, @peer_cert is the certificate
250 * presented by the client, if this was requested via the server's
251 * #GDtlsServerConnection:authentication_mode. On the server side,
252 * the signal is always emitted when the client presents a
253 * certificate, and the certificate will only be accepted if a
254 * handler returns %TRUE.
255 *
256 * Note that if this signal is emitted as part of asynchronous I/O
257 * in the main thread, then you should not attempt to interact with
258 * the user before returning from the signal handler. If you want to
259 * let the user decide whether or not to accept the certificate, you
260 * would have to return %FALSE from the signal handler on the first
261 * attempt, and then after the connection attempt returns a
262 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
263 * the user decides to accept the certificate, remember that fact,
264 * create a new connection, and return %TRUE from the signal handler
265 * the next time.
266 *
267 * If you are doing I/O in another thread, you do not
268 * need to worry about this, and can simply block in the signal
269 * handler until the UI thread returns an answer.
270 *
271 * Returns: %TRUE to accept @peer_cert (which will also
272 * immediately end the signal emission). %FALSE to allow the signal
273 * emission to continue, which will cause the handshake to fail if
274 * no one else overrides it.
275 *
276 * Since: 2.48
277 */
278 signals[ACCEPT_CERTIFICATE] =
279 g_signal_new (I_("accept-certificate"),
280 G_TYPE_DTLS_CONNECTION,
281 G_SIGNAL_RUN_LAST,
282 G_STRUCT_OFFSET (GDtlsConnectionInterface, accept_certificate),
283 g_signal_accumulator_true_handled, NULL,
284 NULL,
285 G_TYPE_BOOLEAN, 2,
286 G_TYPE_TLS_CERTIFICATE,
287 G_TYPE_TLS_CERTIFICATE_FLAGS);
288 }
289  
290 /**
291 * g_dtls_connection_set_database:
292 * @conn: a #GDtlsConnection
293 * @database: a #GTlsDatabase
294 *
295 * Sets the certificate database that is used to verify peer certificates.
296 * This is set to the default database by default. See
297 * g_dtls_backend_get_default_database(). If set to %NULL, then
298 * peer certificate validation will always set the
299 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
300 * #GDtlsConnection::accept-certificate will always be emitted on
301 * client-side connections, unless that bit is not set in
302 * #GDtlsClientConnection:validation-flags).
303 *
304 * Since: 2.48
305 */
306 void
307 g_dtls_connection_set_database (GDtlsConnection *conn,
308 GTlsDatabase *database)
309 {
310 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
311 g_return_if_fail (database == NULL || G_IS_TLS_DATABASE (database));
312  
313 g_object_set (G_OBJECT (conn),
314 "database", database,
315 NULL);
316 }
317  
318 /**
319 * g_dtls_connection_get_database:
320 * @conn: a #GDtlsConnection
321 *
322 * Gets the certificate database that @conn uses to verify
323 * peer certificates. See g_dtls_connection_set_database().
324 *
325 * Returns: (transfer none): the certificate database that @conn uses or %NULL
326 *
327 * Since: 2.48
328 */
329 GTlsDatabase*
330 g_dtls_connection_get_database (GDtlsConnection *conn)
331 {
332 GTlsDatabase *database = NULL;
333  
334 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
335  
336 g_object_get (G_OBJECT (conn),
337 "database", &database,
338 NULL);
339 if (database)
340 g_object_unref (database);
341 return database;
342 }
343  
344 /**
345 * g_dtls_connection_set_certificate:
346 * @conn: a #GDtlsConnection
347 * @certificate: the certificate to use for @conn
348 *
349 * This sets the certificate that @conn will present to its peer
350 * during the TLS handshake. For a #GDtlsServerConnection, it is
351 * mandatory to set this, and that will normally be done at construct
352 * time.
353 *
354 * For a #GDtlsClientConnection, this is optional. If a handshake fails
355 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
356 * requires a certificate, and if you try connecting again, you should
357 * call this method first. You can call
358 * g_dtls_client_connection_get_accepted_cas() on the failed connection
359 * to get a list of Certificate Authorities that the server will
360 * accept certificates from.
361 *
362 * (It is also possible that a server will allow the connection with
363 * or without a certificate; in that case, if you don't provide a
364 * certificate, you can tell that the server requested one by the fact
365 * that g_dtls_client_connection_get_accepted_cas() will return
366 * non-%NULL.)
367 *
368 * Since: 2.48
369 */
370 void
371 g_dtls_connection_set_certificate (GDtlsConnection *conn,
372 GTlsCertificate *certificate)
373 {
374 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
375 g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
376  
377 g_object_set (G_OBJECT (conn), "certificate", certificate, NULL);
378 }
379  
380 /**
381 * g_dtls_connection_get_certificate:
382 * @conn: a #GDtlsConnection
383 *
384 * Gets @conn's certificate, as set by
385 * g_dtls_connection_set_certificate().
386 *
387 * Returns: (transfer none): @conn's certificate, or %NULL
388 *
389 * Since: 2.48
390 */
391 GTlsCertificate *
392 g_dtls_connection_get_certificate (GDtlsConnection *conn)
393 {
394 GTlsCertificate *certificate;
395  
396 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
397  
398 g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
399 if (certificate)
400 g_object_unref (certificate);
401  
402 return certificate;
403 }
404  
405 /**
406 * g_dtls_connection_set_interaction:
407 * @conn: a connection
408 * @interaction: (allow-none): an interaction object, or %NULL
409 *
410 * Set the object that will be used to interact with the user. It will be used
411 * for things like prompting the user for passwords.
412 *
413 * The @interaction argument will normally be a derived subclass of
414 * #GTlsInteraction. %NULL can also be provided if no user interaction
415 * should occur for this connection.
416 *
417 * Since: 2.48
418 */
419 void
420 g_dtls_connection_set_interaction (GDtlsConnection *conn,
421 GTlsInteraction *interaction)
422 {
423 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
424 g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
425  
426 g_object_set (G_OBJECT (conn), "interaction", interaction, NULL);
427 }
428  
429 /**
430 * g_dtls_connection_get_interaction:
431 * @conn: a connection
432 *
433 * Get the object that will be used to interact with the user. It will be used
434 * for things like prompting the user for passwords. If %NULL is returned, then
435 * no user interaction will occur for this connection.
436 *
437 * Returns: (transfer none): The interaction object.
438 *
439 * Since: 2.48
440 */
441 GTlsInteraction *
442 g_dtls_connection_get_interaction (GDtlsConnection *conn)
443 {
444 GTlsInteraction *interaction = NULL;
445  
446 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
447  
448 g_object_get (G_OBJECT (conn), "interaction", &interaction, NULL);
449 if (interaction)
450 g_object_unref (interaction);
451  
452 return interaction;
453 }
454  
455 /**
456 * g_dtls_connection_get_peer_certificate:
457 * @conn: a #GDtlsConnection
458 *
459 * Gets @conn's peer's certificate after the handshake has completed.
460 * (It is not set during the emission of
461 * #GDtlsConnection::accept-certificate.)
462 *
463 * Returns: (transfer none): @conn's peer's certificate, or %NULL
464 *
465 * Since: 2.48
466 */
467 GTlsCertificate *
468 g_dtls_connection_get_peer_certificate (GDtlsConnection *conn)
469 {
470 GTlsCertificate *peer_certificate;
471  
472 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), NULL);
473  
474 g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
475 if (peer_certificate)
476 g_object_unref (peer_certificate);
477  
478 return peer_certificate;
479 }
480  
481 /**
482 * g_dtls_connection_get_peer_certificate_errors:
483 * @conn: a #GDtlsConnection
484 *
485 * Gets the errors associated with validating @conn's peer's
486 * certificate, after the handshake has completed. (It is not set
487 * during the emission of #GDtlsConnection::accept-certificate.)
488 *
489 * Returns: @conn's peer's certificate errors
490 *
491 * Since: 2.48
492 */
493 GTlsCertificateFlags
494 g_dtls_connection_get_peer_certificate_errors (GDtlsConnection *conn)
495 {
496 GTlsCertificateFlags errors;
497  
498 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), 0);
499  
500 g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
501 return errors;
502 }
503  
504 /**
505 * g_dtls_connection_set_require_close_notify:
506 * @conn: a #GDtlsConnection
507 * @require_close_notify: whether or not to require close notification
508 *
509 * Sets whether or not @conn expects a proper TLS close notification
510 * before the connection is closed. If this is %TRUE (the default),
511 * then @conn will expect to receive a TLS close notification from its
512 * peer before the connection is closed, and will return a
513 * %G_TLS_ERROR_EOF error if the connection is closed without proper
514 * notification (since this may indicate a network error, or
515 * man-in-the-middle attack).
516 *
517 * In some protocols, the application will know whether or not the
518 * connection was closed cleanly based on application-level data
519 * (because the application-level data includes a length field, or is
520 * somehow self-delimiting); in this case, the close notify is
521 * redundant and may be omitted. You
522 * can use g_dtls_connection_set_require_close_notify() to tell @conn
523 * to allow an "unannounced" connection close, in which case the close
524 * will show up as a 0-length read, as in a non-TLS
525 * #GDatagramBased, and it is up to the application to check that
526 * the data has been fully received.
527 *
528 * Note that this only affects the behavior when the peer closes the
529 * connection; when the application calls g_dtls_connection_close_async() on
530 * @conn itself, this will send a close notification regardless of the
531 * setting of this property. If you explicitly want to do an unclean
532 * close, you can close @conn's #GDtlsConnection:base-socket rather
533 * than closing @conn itself.
534 *
535 * Since: 2.48
536 */
537 void
538 g_dtls_connection_set_require_close_notify (GDtlsConnection *conn,
539 gboolean require_close_notify)
540 {
541 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
542  
543 g_object_set (G_OBJECT (conn),
544 "require-close-notify", require_close_notify,
545 NULL);
546 }
547  
548 /**
549 * g_dtls_connection_get_require_close_notify:
550 * @conn: a #GDtlsConnection
551 *
552 * Tests whether or not @conn expects a proper TLS close notification
553 * when the connection is closed. See
554 * g_dtls_connection_set_require_close_notify() for details.
555 *
556 * Returns: %TRUE if @conn requires a proper TLS close notification.
557 *
558 * Since: 2.48
559 */
560 gboolean
561 g_dtls_connection_get_require_close_notify (GDtlsConnection *conn)
562 {
563 gboolean require_close_notify;
564  
565 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), TRUE);
566  
567 g_object_get (G_OBJECT (conn),
568 "require-close-notify", &require_close_notify,
569 NULL);
570 return require_close_notify;
571 }
572  
573 /**
574 * g_dtls_connection_set_rehandshake_mode:
575 * @conn: a #GDtlsConnection
576 * @mode: the rehandshaking mode
577 *
578 * Sets how @conn behaves with respect to rehandshaking requests.
579 *
580 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
581 * rehandshake after the initial handshake is complete. (For a client,
582 * this means it will refuse rehandshake requests from the server, and
583 * for a server, this means it will close the connection with an error
584 * if the client attempts to rehandshake.)
585 *
586 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
587 * rehandshake only if the other end of the connection supports the
588 * TLS `renegotiation_info` extension. This is the default behavior,
589 * but means that rehandshaking will not work against older
590 * implementations that do not support that extension.
591 *
592 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
593 * rehandshaking even without the `renegotiation_info` extension. On
594 * the server side in particular, this is not recommended, since it
595 * leaves the server open to certain attacks. However, this mode is
596 * necessary if you need to allow renegotiation with older client
597 * software.
598 *
599 * Since: 2.48
600 */
601 void
602 g_dtls_connection_set_rehandshake_mode (GDtlsConnection *conn,
603 GTlsRehandshakeMode mode)
604 {
605 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
606  
607 g_object_set (G_OBJECT (conn),
608 "rehandshake-mode", mode,
609 NULL);
610 }
611  
612 /**
613 * g_dtls_connection_get_rehandshake_mode:
614 * @conn: a #GDtlsConnection
615 *
616 * Gets @conn rehandshaking mode. See
617 * g_dtls_connection_set_rehandshake_mode() for details.
618 *
619 * Returns: @conn's rehandshaking mode
620 *
621 * Since: 2.48
622 */
623 GTlsRehandshakeMode
624 g_dtls_connection_get_rehandshake_mode (GDtlsConnection *conn)
625 {
626 GTlsRehandshakeMode mode;
627  
628 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), G_TLS_REHANDSHAKE_NEVER);
629  
630 g_object_get (G_OBJECT (conn),
631 "rehandshake-mode", &mode,
632 NULL);
633 return mode;
634 }
635  
636 /**
637 * g_dtls_connection_handshake:
638 * @conn: a #GDtlsConnection
639 * @cancellable: (allow-none): a #GCancellable, or %NULL
640 * @error: a #GError, or %NULL
641 *
642 * Attempts a TLS handshake on @conn.
643 *
644 * On the client side, it is never necessary to call this method;
645 * although the connection needs to perform a handshake after
646 * connecting (or after sending a "STARTTLS"-type command) and may
647 * need to rehandshake later if the server requests it,
648 * #GDtlsConnection will handle this for you automatically when you try
649 * to send or receive data on the connection. However, you can call
650 * g_dtls_connection_handshake() manually if you want to know for sure
651 * whether the initial handshake succeeded or failed (as opposed to
652 * just immediately trying to write to @conn, in which
653 * case if it fails, it may not be possible to tell if it failed
654 * before or after completing the handshake).
655 *
656 * Likewise, on the server side, although a handshake is necessary at
657 * the beginning of the communication, you do not need to call this
658 * function explicitly unless you want clearer error reporting.
659 * However, you may call g_dtls_connection_handshake() later on to
660 * renegotiate parameters (encryption methods, etc) with the client.
661 *
662 * #GDtlsConnection::accept_certificate may be emitted during the
663 * handshake.
664 *
665 * Returns: success or failure
666 *
667 * Since: 2.48
668 */
669 gboolean
670 g_dtls_connection_handshake (GDtlsConnection *conn,
671 GCancellable *cancellable,
672 GError **error)
673 {
674 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
675  
676 return G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake (conn, cancellable,
677 error);
678 }
679  
680 /**
681 * g_dtls_connection_handshake_async:
682 * @conn: a #GDtlsConnection
683 * @io_priority: the [I/O priority][io-priority] of the request
684 * @cancellable: (allow-none): a #GCancellable, or %NULL
685 * @callback: callback to call when the handshake is complete
686 * @user_data: the data to pass to the callback function
687 *
688 * Asynchronously performs a TLS handshake on @conn. See
689 * g_dtls_connection_handshake() for more information.
690 *
691 * Since: 2.48
692 */
693 void
694 g_dtls_connection_handshake_async (GDtlsConnection *conn,
695 int io_priority,
696 GCancellable *cancellable,
697 GAsyncReadyCallback callback,
698 gpointer user_data)
699 {
700 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
701  
702 G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake_async (conn, io_priority,
703 cancellable,
704 callback, user_data);
705 }
706  
707 /**
708 * g_dtls_connection_handshake_finish:
709 * @conn: a #GDtlsConnection
710 * @result: a #GAsyncResult.
711 * @error: a #GError pointer, or %NULL
712 *
713 * Finish an asynchronous TLS handshake operation. See
714 * g_dtls_connection_handshake() for more information.
715 *
716 * Returns: %TRUE on success, %FALSE on failure, in which
717 * case @error will be set.
718 *
719 * Since: 2.48
720 */
721 gboolean
722 g_dtls_connection_handshake_finish (GDtlsConnection *conn,
723 GAsyncResult *result,
724 GError **error)
725 {
726 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
727  
728 return G_DTLS_CONNECTION_GET_INTERFACE (conn)->handshake_finish (conn,
729 result,
730 error);
731 }
732  
733 /**
734 * g_dtls_connection_shutdown:
735 * @conn: a #GDtlsConnection
736 * @shutdown_read: %TRUE to stop reception of incoming datagrams
737 * @shutdown_write: %TRUE to stop sending outgoing datagrams
738 * @cancellable: (nullable): a #GCancellable, or %NULL
739 * @error: a #GError, or %NULL
740 *
741 * Shut down part or all of a DTLS connection.
742 *
743 * If @shutdown_read is %TRUE then the receiving side of the connection is shut
744 * down, and further reading is disallowed. Subsequent calls to
745 * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
746 *
747 * If @shutdown_write is %TRUE then the sending side of the connection is shut
748 * down, and further writing is disallowed. Subsequent calls to
749 * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
750 *
751 * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
752 * is equivalent to calling g_dtls_connection_close().
753 *
754 * If @cancellable is cancelled, the #GDtlsConnection may be left
755 * partially-closed and any pending untransmitted data may be lost. Call
756 * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
757 *
758 * Returns: %TRUE on success, %FALSE otherwise
759 *
760 * Since: 2.48
761 */
762 gboolean
763 g_dtls_connection_shutdown (GDtlsConnection *conn,
764 gboolean shutdown_read,
765 gboolean shutdown_write,
766 GCancellable *cancellable,
767 GError **error)
768 {
769 GDtlsConnectionInterface *iface;
770  
771 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
772 g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
773 FALSE);
774 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
775  
776 if (!shutdown_read && !shutdown_write)
777 return TRUE;
778  
779 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
780 g_assert (iface->shutdown != NULL);
781  
782 return iface->shutdown (conn, shutdown_read, shutdown_write,
783 cancellable, error);
784 }
785  
786 /**
787 * g_dtls_connection_shutdown_async:
788 * @conn: a #GDtlsConnection
789 * @shutdown_read: %TRUE to stop reception of incoming datagrams
790 * @shutdown_write: %TRUE to stop sending outgoing datagrams
791 * @io_priority: the [I/O priority][io-priority] of the request
792 * @cancellable: (nullable): a #GCancellable, or %NULL
793 * @callback: callback to call when the shutdown operation is complete
794 * @user_data: the data to pass to the callback function
795 *
796 * Asynchronously shut down part or all of the DTLS connection. See
797 * g_dtls_connection_shutdown() for more information.
798 *
799 * Since: 2.48
800 */
801 void
802 g_dtls_connection_shutdown_async (GDtlsConnection *conn,
803 gboolean shutdown_read,
804 gboolean shutdown_write,
805 int io_priority,
806 GCancellable *cancellable,
807 GAsyncReadyCallback callback,
808 gpointer user_data)
809 {
810 GDtlsConnectionInterface *iface;
811  
812 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
813 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
814  
815 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
816 g_assert (iface->shutdown_async != NULL);
817  
818 iface->shutdown_async (conn, TRUE, TRUE, io_priority, cancellable,
819 callback, user_data);
820 }
821  
822 /**
823 * g_dtls_connection_shutdown_finish:
824 * @conn: a #GDtlsConnection
825 * @result: a #GAsyncResult
826 * @error: a #GError pointer, or %NULL
827 *
828 * Finish an asynchronous TLS shutdown operation. See
829 * g_dtls_connection_shutdown() for more information.
830 *
831 * Returns: %TRUE on success, %FALSE on failure, in which
832 * case @error will be set
833 *
834 * Since: 2.48
835 */
836 gboolean
837 g_dtls_connection_shutdown_finish (GDtlsConnection *conn,
838 GAsyncResult *result,
839 GError **error)
840 {
841 GDtlsConnectionInterface *iface;
842  
843 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
844 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
845  
846 iface = G_DTLS_CONNECTION_GET_INTERFACE (conn);
847 g_assert (iface->shutdown_finish != NULL);
848  
849 return iface->shutdown_finish (conn, result, error);
850 }
851  
852 /**
853 * g_dtls_connection_close:
854 * @conn: a #GDtlsConnection
855 * @cancellable: (nullable): a #GCancellable, or %NULL
856 * @error: a #GError, or %NULL
857 *
858 * Close the DTLS connection. This is equivalent to calling
859 * g_dtls_connection_shutdown() to shut down both sides of the connection.
860 *
861 * Closing a #GDtlsConnection waits for all buffered but untransmitted data to
862 * be sent before it completes. It then sends a `close_notify` DTLS alert to the
863 * peer and may wait for a `close_notify` to be received from the peer. It does
864 * not close the underlying #GDtlsConnection:base-socket; that must be closed
865 * separately.
866 *
867 * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED.
868 * Closing a #GDtlsConnection multiple times will not return an error.
869 *
870 * #GDtlsConnections will be automatically closed when the last reference is
871 * dropped, but you might want to call this function to make sure resources are
872 * released as early as possible.
873 *
874 * If @cancellable is cancelled, the #GDtlsConnection may be left
875 * partially-closed and any pending untransmitted data may be lost. Call
876 * g_dtls_connection_close() again to complete closing the #GDtlsConnection.
877 *
878 * Returns: %TRUE on success, %FALSE otherwise
879 *
880 * Since: 2.48
881 */
882 gboolean
883 g_dtls_connection_close (GDtlsConnection *conn,
884 GCancellable *cancellable,
885 GError **error)
886 {
887 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
888 g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable),
889 FALSE);
890 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
891  
892 return G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown (conn, TRUE, TRUE,
893 cancellable, error);
894 }
895  
896 /**
897 * g_dtls_connection_close_async:
898 * @conn: a #GDtlsConnection
899 * @io_priority: the [I/O priority][io-priority] of the request
900 * @cancellable: (nullable): a #GCancellable, or %NULL
901 * @callback: callback to call when the close operation is complete
902 * @user_data: the data to pass to the callback function
903 *
904 * Asynchronously close the DTLS connection. See g_dtls_connection_close() for
905 * more information.
906 *
907 * Since: 2.48
908 */
909 void
910 g_dtls_connection_close_async (GDtlsConnection *conn,
911 int io_priority,
912 GCancellable *cancellable,
913 GAsyncReadyCallback callback,
914 gpointer user_data)
915 {
916 g_return_if_fail (G_IS_DTLS_CONNECTION (conn));
917 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
918  
919 G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown_async (conn, TRUE, TRUE,
920 io_priority,
921 cancellable,
922 callback, user_data);
923 }
924  
925 /**
926 * g_dtls_connection_close_finish:
927 * @conn: a #GDtlsConnection
928 * @result: a #GAsyncResult
929 * @error: a #GError pointer, or %NULL
930 *
931 * Finish an asynchronous TLS close operation. See g_dtls_connection_close()
932 * for more information.
933 *
934 * Returns: %TRUE on success, %FALSE on failure, in which
935 * case @error will be set
936 *
937 * Since: 2.48
938 */
939 gboolean
940 g_dtls_connection_close_finish (GDtlsConnection *conn,
941 GAsyncResult *result,
942 GError **error)
943 {
944 g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
945 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
946  
947 return G_DTLS_CONNECTION_GET_INTERFACE (conn)->shutdown_finish (conn, result,
948 error);
949 }
950  
951 /**
952 * g_dtls_connection_emit_accept_certificate:
953 * @conn: a #GDtlsConnection
954 * @peer_cert: the peer's #GTlsCertificate
955 * @errors: the problems with @peer_cert
956 *
957 * Used by #GDtlsConnection implementations to emit the
958 * #GDtlsConnection::accept-certificate signal.
959 *
960 * Returns: %TRUE if one of the signal handlers has returned
961 * %TRUE to accept @peer_cert
962 *
963 * Since: 2.48
964 */
965 gboolean
966 g_dtls_connection_emit_accept_certificate (GDtlsConnection *conn,
967 GTlsCertificate *peer_cert,
968 GTlsCertificateFlags errors)
969 {
970 gboolean accept = FALSE;
971  
972 g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
973 peer_cert, errors, &accept);
974 return accept;
975 }