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