1 /* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright © 2010 Red Hat, Inc
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 */
18
19 #include "config.h"
20 #include "glib.h"
21
22 #include "gtlsconnection.h"
23 #include "gcancellable.h"
24 #include "gioenumtypes.h"
25 #include "gsocket.h"
26 #include "gtlsbackend.h"
27 #include "gtlscertificate.h"
28 #include "gtlsclientconnection.h"
29 #include "gtlsdatabase.h"
30 #include "gtlsinteraction.h"
31 #include "glibintl.h"
32 #include "gmarshal-internal.h"
33
34 /**
35 * SECTION:gtlsconnection
36 * @short_description: TLS connection type
37 * @include: gio/gio.h
38 *
39 * #GTlsConnection is the base TLS connection class type, which wraps
40 * a #GIOStream and provides TLS encryption on top of it. Its
41 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
42 * implement client-side and server-side TLS, respectively.
43 *
44 * For DTLS (Datagram TLS) support, see #GDtlsConnection.
45 *
46 * Since: 2.28
47 */
48
49 /**
50 * GTlsConnection:
51 *
52 * Abstract base class for the backend-specific #GTlsClientConnection
53 * and #GTlsServerConnection types.
54 *
55 * Since: 2.28
56 */
57
58 struct _GTlsConnectionPrivate
59 {
60 gchar *negotiated_protocol;
61 };
62
63 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GTlsConnection, g_tls_connection, G_TYPE_IO_STREAM)
64
65 static void g_tls_connection_get_property (GObject *object,
66 guint prop_id,
67 GValue *value,
68 GParamSpec *pspec);
69 static void g_tls_connection_set_property (GObject *object,
70 guint prop_id,
71 const GValue *value,
72 GParamSpec *pspec);
73 static void g_tls_connection_finalize (GObject *object);
74
75 enum {
76 ACCEPT_CERTIFICATE,
77
78 LAST_SIGNAL
79 };
80
81 static guint signals[LAST_SIGNAL] = { 0 };
82
83 enum {
84 PROP_0,
85 PROP_BASE_IO_STREAM,
86 PROP_REQUIRE_CLOSE_NOTIFY,
87 PROP_REHANDSHAKE_MODE,
88 PROP_USE_SYSTEM_CERTDB,
89 PROP_DATABASE,
90 PROP_INTERACTION,
91 PROP_CERTIFICATE,
92 PROP_PEER_CERTIFICATE,
93 PROP_PEER_CERTIFICATE_ERRORS,
94 PROP_ADVERTISED_PROTOCOLS,
95 PROP_NEGOTIATED_PROTOCOL,
96 };
97
98 static void
g_tls_connection_class_init(GTlsConnectionClass * klass)99 g_tls_connection_class_init (GTlsConnectionClass *klass)
100 {
101 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
102
103 gobject_class->get_property = g_tls_connection_get_property;
104 gobject_class->set_property = g_tls_connection_set_property;
105 gobject_class->finalize = g_tls_connection_finalize;
106
107 /**
108 * GTlsConnection:base-io-stream:
109 *
110 * The #GIOStream that the connection wraps. The connection holds a reference
111 * to this stream, and may run operations on the stream from other threads
112 * throughout its lifetime. Consequently, after the #GIOStream has been
113 * constructed, application code may only run its own operations on this
114 * stream when no #GIOStream operations are running.
115 *
116 * Since: 2.28
117 */
118 g_object_class_install_property (gobject_class, PROP_BASE_IO_STREAM,
119 g_param_spec_object ("base-io-stream",
120 P_("Base IOStream"),
121 P_("The GIOStream that the connection wraps"),
122 G_TYPE_IO_STREAM,
123 G_PARAM_READWRITE |
124 G_PARAM_CONSTRUCT_ONLY |
125 G_PARAM_STATIC_STRINGS));
126 /**
127 * GTlsConnection:use-system-certdb:
128 *
129 * Whether or not the system certificate database will be used to
130 * verify peer certificates. See
131 * g_tls_connection_set_use_system_certdb().
132 *
133 * Deprecated: 2.30: Use GTlsConnection:database instead
134 */
135 g_object_class_install_property (gobject_class, PROP_USE_SYSTEM_CERTDB,
136 g_param_spec_boolean ("use-system-certdb",
137 P_("Use system certificate database"),
138 P_("Whether to verify peer certificates against the system certificate database"),
139 TRUE,
140 G_PARAM_READWRITE |
141 G_PARAM_CONSTRUCT |
142 G_PARAM_STATIC_STRINGS |
143 G_PARAM_DEPRECATED));
144 /**
145 * GTlsConnection:database: (nullable)
146 *
147 * The certificate database to use when verifying this TLS connection.
148 * If no certificate database is set, then the default database will be
149 * used. See g_tls_backend_get_default_database().
150 *
151 * Since: 2.30
152 */
153 g_object_class_install_property (gobject_class, PROP_DATABASE,
154 g_param_spec_object ("database",
155 P_("Database"),
156 P_("Certificate database to use for looking up or verifying certificates"),
157 G_TYPE_TLS_DATABASE,
158 G_PARAM_READWRITE |
159 G_PARAM_STATIC_STRINGS));
160 /**
161 * GTlsConnection:interaction: (nullable)
162 *
163 * A #GTlsInteraction object to be used when the connection or certificate
164 * database need to interact with the user. This will be used to prompt the
165 * user for passwords where necessary.
166 *
167 * Since: 2.30
168 */
169 g_object_class_install_property (gobject_class, PROP_INTERACTION,
170 g_param_spec_object ("interaction",
171 P_("Interaction"),
172 P_("Optional object for user interaction"),
173 G_TYPE_TLS_INTERACTION,
174 G_PARAM_READWRITE |
175 G_PARAM_STATIC_STRINGS));
176 /**
177 * GTlsConnection:require-close-notify:
178 *
179 * Whether or not proper TLS close notification is required.
180 * See g_tls_connection_set_require_close_notify().
181 *
182 * Since: 2.28
183 */
184 g_object_class_install_property (gobject_class, PROP_REQUIRE_CLOSE_NOTIFY,
185 g_param_spec_boolean ("require-close-notify",
186 P_("Require close notify"),
187 P_("Whether to require proper TLS close notification"),
188 TRUE,
189 G_PARAM_READWRITE |
190 G_PARAM_CONSTRUCT |
191 G_PARAM_STATIC_STRINGS));
192 /**
193 * GTlsConnection:rehandshake-mode:
194 *
195 * The rehandshaking mode. See
196 * g_tls_connection_set_rehandshake_mode().
197 *
198 * Since: 2.28
199 *
200 * Deprecated: 2.60: The rehandshake mode is ignored.
201 */
202 g_object_class_install_property (gobject_class, PROP_REHANDSHAKE_MODE,
203 g_param_spec_enum ("rehandshake-mode",
204 P_("Rehandshake mode"),
205 P_("When to allow rehandshaking"),
206 G_TYPE_TLS_REHANDSHAKE_MODE,
207 G_TLS_REHANDSHAKE_SAFELY,
208 G_PARAM_READWRITE |
209 G_PARAM_CONSTRUCT |
210 G_PARAM_STATIC_STRINGS |
211 G_PARAM_DEPRECATED));
212 /**
213 * GTlsConnection:certificate:
214 *
215 * The connection's certificate; see
216 * g_tls_connection_set_certificate().
217 *
218 * Since: 2.28
219 */
220 g_object_class_install_property (gobject_class, PROP_CERTIFICATE,
221 g_param_spec_object ("certificate",
222 P_("Certificate"),
223 P_("The connection’s certificate"),
224 G_TYPE_TLS_CERTIFICATE,
225 G_PARAM_READWRITE |
226 G_PARAM_STATIC_STRINGS));
227 /**
228 * GTlsConnection:peer-certificate: (nullable)
229 *
230 * The connection's peer's certificate, after the TLS handshake has
231 * completed or failed. Note in particular that this is not yet set
232 * during the emission of #GTlsConnection::accept-certificate.
233 *
234 * (You can watch for a #GObject::notify signal on this property to
235 * detect when a handshake has occurred.)
236 *
237 * Since: 2.28
238 */
239 g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE,
240 g_param_spec_object ("peer-certificate",
241 P_("Peer Certificate"),
242 P_("The connection’s peer’s certificate"),
243 G_TYPE_TLS_CERTIFICATE,
244 G_PARAM_READABLE |
245 G_PARAM_STATIC_STRINGS));
246 /**
247 * GTlsConnection:peer-certificate-errors:
248 *
249 * The errors noticed while verifying
250 * #GTlsConnection:peer-certificate. Normally this should be 0, but
251 * it may not be if #GTlsClientConnection:validation-flags is not
252 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
253 * #GTlsConnection::accept-certificate overrode the default
254 * behavior.
255 *
256 * Since: 2.28
257 */
258 g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE_ERRORS,
259 g_param_spec_flags ("peer-certificate-errors",
260 P_("Peer Certificate Errors"),
261 P_("Errors found with the peer’s certificate"),
262 G_TYPE_TLS_CERTIFICATE_FLAGS,
263 0,
264 G_PARAM_READABLE |
265 G_PARAM_STATIC_STRINGS));
266 /**
267 * GTlsConnection:advertised-protocols: (nullable)
268 *
269 * The list of application-layer protocols that the connection
270 * advertises that it is willing to speak. See
271 * g_tls_connection_set_advertised_protocols().
272 *
273 * Since: 2.60
274 */
275 g_object_class_install_property (gobject_class, PROP_ADVERTISED_PROTOCOLS,
276 g_param_spec_boxed ("advertised-protocols",
277 P_("Advertised Protocols"),
278 P_("Application-layer protocols available on this connection"),
279 G_TYPE_STRV,
280 G_PARAM_READWRITE |
281 G_PARAM_STATIC_STRINGS));
282 /**
283 * GTlsConnection:negotiated-protocol:
284 *
285 * The application-layer protocol negotiated during the TLS
286 * handshake. See g_tls_connection_get_negotiated_protocol().
287 *
288 * Since: 2.60
289 */
290 g_object_class_install_property (gobject_class, PROP_NEGOTIATED_PROTOCOL,
291 g_param_spec_string ("negotiated-protocol",
292 P_("Negotiated Protocol"),
293 P_("Application-layer protocol negotiated for this connection"),
294 NULL,
295 G_PARAM_READABLE |
296 G_PARAM_STATIC_STRINGS));
297
298 /**
299 * GTlsConnection::accept-certificate:
300 * @conn: a #GTlsConnection
301 * @peer_cert: the peer's #GTlsCertificate
302 * @errors: the problems with @peer_cert.
303 *
304 * Emitted during the TLS handshake after the peer certificate has
305 * been received. You can examine @peer_cert's certification path by
306 * calling g_tls_certificate_get_issuer() on it.
307 *
308 * For a client-side connection, @peer_cert is the server's
309 * certificate, and the signal will only be emitted if the
310 * certificate was not acceptable according to @conn's
311 * #GTlsClientConnection:validation_flags. If you would like the
312 * certificate to be accepted despite @errors, return %TRUE from the
313 * signal handler. Otherwise, if no handler accepts the certificate,
314 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
315 *
316 * For a server-side connection, @peer_cert is the certificate
317 * presented by the client, if this was requested via the server's
318 * #GTlsServerConnection:authentication_mode. On the server side,
319 * the signal is always emitted when the client presents a
320 * certificate, and the certificate will only be accepted if a
321 * handler returns %TRUE.
322 *
323 * Note that if this signal is emitted as part of asynchronous I/O
324 * in the main thread, then you should not attempt to interact with
325 * the user before returning from the signal handler. If you want to
326 * let the user decide whether or not to accept the certificate, you
327 * would have to return %FALSE from the signal handler on the first
328 * attempt, and then after the connection attempt returns a
329 * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
330 * if the user decides to accept the certificate, remember that fact,
331 * create a new connection, and return %TRUE from the signal handler
332 * the next time.
333 *
334 * If you are doing I/O in another thread, you do not
335 * need to worry about this, and can simply block in the signal
336 * handler until the UI thread returns an answer.
337 *
338 * Returns: %TRUE to accept @peer_cert (which will also
339 * immediately end the signal emission). %FALSE to allow the signal
340 * emission to continue, which will cause the handshake to fail if
341 * no one else overrides it.
342 *
343 * Since: 2.28
344 */
345 signals[ACCEPT_CERTIFICATE] =
346 g_signal_new (I_("accept-certificate"),
347 G_TYPE_TLS_CONNECTION,
348 G_SIGNAL_RUN_LAST,
349 G_STRUCT_OFFSET (GTlsConnectionClass, accept_certificate),
350 g_signal_accumulator_true_handled, NULL,
351 _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGS,
352 G_TYPE_BOOLEAN, 2,
353 G_TYPE_TLS_CERTIFICATE,
354 G_TYPE_TLS_CERTIFICATE_FLAGS);
355 g_signal_set_va_marshaller (signals[ACCEPT_CERTIFICATE],
356 G_TYPE_FROM_CLASS (klass),
357 _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGSv);
358 }
359
360 static void
g_tls_connection_init(GTlsConnection * conn)361 g_tls_connection_init (GTlsConnection *conn)
362 {
363 }
364
365 static void
g_tls_connection_get_property(GObject * object,guint prop_id,GValue * value,GParamSpec * pspec)366 g_tls_connection_get_property (GObject *object,
367 guint prop_id,
368 GValue *value,
369 GParamSpec *pspec)
370 {
371 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
372 }
373
374 static void
g_tls_connection_set_property(GObject * object,guint prop_id,const GValue * value,GParamSpec * pspec)375 g_tls_connection_set_property (GObject *object,
376 guint prop_id,
377 const GValue *value,
378 GParamSpec *pspec)
379 {
380 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
381 }
382
383 static void
g_tls_connection_finalize(GObject * object)384 g_tls_connection_finalize (GObject *object)
385 {
386 GTlsConnection *conn = G_TLS_CONNECTION(object);
387 GTlsConnectionPrivate *priv = g_tls_connection_get_instance_private (conn);
388
389 g_clear_pointer (&priv->negotiated_protocol, g_free);
390
391 G_OBJECT_CLASS (g_tls_connection_parent_class)->finalize (object);
392 }
393
394 /**
395 * g_tls_connection_set_use_system_certdb:
396 * @conn: a #GTlsConnection
397 * @use_system_certdb: whether to use the system certificate database
398 *
399 * Sets whether @conn uses the system certificate database to verify
400 * peer certificates. This is %TRUE by default. If set to %FALSE, then
401 * peer certificate validation will always set the
402 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
403 * #GTlsConnection::accept-certificate will always be emitted on
404 * client-side connections, unless that bit is not set in
405 * #GTlsClientConnection:validation-flags).
406 *
407 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
408 */
409 void
g_tls_connection_set_use_system_certdb(GTlsConnection * conn,gboolean use_system_certdb)410 g_tls_connection_set_use_system_certdb (GTlsConnection *conn,
411 gboolean use_system_certdb)
412 {
413 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
414
415 g_object_set (G_OBJECT (conn),
416 "use-system-certdb", use_system_certdb,
417 NULL);
418 }
419
420 /**
421 * g_tls_connection_get_use_system_certdb:
422 * @conn: a #GTlsConnection
423 *
424 * Gets whether @conn uses the system certificate database to verify
425 * peer certificates. See g_tls_connection_set_use_system_certdb().
426 *
427 * Returns: whether @conn uses the system certificate database
428 *
429 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
430 */
431 gboolean
g_tls_connection_get_use_system_certdb(GTlsConnection * conn)432 g_tls_connection_get_use_system_certdb (GTlsConnection *conn)
433 {
434 gboolean use_system_certdb;
435
436 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
437
438 g_object_get (G_OBJECT (conn),
439 "use-system-certdb", &use_system_certdb,
440 NULL);
441 return use_system_certdb;
442 }
443
444 /**
445 * g_tls_connection_set_database:
446 * @conn: a #GTlsConnection
447 * @database: (nullable): a #GTlsDatabase
448 *
449 * Sets the certificate database that is used to verify peer certificates.
450 * This is set to the default database by default. See
451 * g_tls_backend_get_default_database(). If set to %NULL, then
452 * peer certificate validation will always set the
453 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
454 * #GTlsConnection::accept-certificate will always be emitted on
455 * client-side connections, unless that bit is not set in
456 * #GTlsClientConnection:validation-flags).
457 *
458 * Since: 2.30
459 */
460 void
g_tls_connection_set_database(GTlsConnection * conn,GTlsDatabase * database)461 g_tls_connection_set_database (GTlsConnection *conn,
462 GTlsDatabase *database)
463 {
464 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
465 g_return_if_fail (database == NULL || G_IS_TLS_DATABASE (database));
466
467 g_object_set (G_OBJECT (conn),
468 "database", database,
469 NULL);
470 }
471
472 /**
473 * g_tls_connection_get_database:
474 * @conn: a #GTlsConnection
475 *
476 * Gets the certificate database that @conn uses to verify
477 * peer certificates. See g_tls_connection_set_database().
478 *
479 * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL
480 *
481 * Since: 2.30
482 */
483 GTlsDatabase*
g_tls_connection_get_database(GTlsConnection * conn)484 g_tls_connection_get_database (GTlsConnection *conn)
485 {
486 GTlsDatabase *database = NULL;
487
488 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
489
490 g_object_get (G_OBJECT (conn),
491 "database", &database,
492 NULL);
493 if (database)
494 g_object_unref (database);
495 return database;
496 }
497
498 /**
499 * g_tls_connection_set_certificate:
500 * @conn: a #GTlsConnection
501 * @certificate: the certificate to use for @conn
502 *
503 * This sets the certificate that @conn will present to its peer
504 * during the TLS handshake. For a #GTlsServerConnection, it is
505 * mandatory to set this, and that will normally be done at construct
506 * time.
507 *
508 * For a #GTlsClientConnection, this is optional. If a handshake fails
509 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
510 * requires a certificate, and if you try connecting again, you should
511 * call this method first. You can call
512 * g_tls_client_connection_get_accepted_cas() on the failed connection
513 * to get a list of Certificate Authorities that the server will
514 * accept certificates from.
515 *
516 * (It is also possible that a server will allow the connection with
517 * or without a certificate; in that case, if you don't provide a
518 * certificate, you can tell that the server requested one by the fact
519 * that g_tls_client_connection_get_accepted_cas() will return
520 * non-%NULL.)
521 *
522 * Since: 2.28
523 */
524 void
g_tls_connection_set_certificate(GTlsConnection * conn,GTlsCertificate * certificate)525 g_tls_connection_set_certificate (GTlsConnection *conn,
526 GTlsCertificate *certificate)
527 {
528 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
529 g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
530
531 g_object_set (G_OBJECT (conn), "certificate", certificate, NULL);
532 }
533
534 /**
535 * g_tls_connection_get_certificate:
536 * @conn: a #GTlsConnection
537 *
538 * Gets @conn's certificate, as set by
539 * g_tls_connection_set_certificate().
540 *
541 * Returns: (transfer none) (nullable): @conn's certificate, or %NULL
542 *
543 * Since: 2.28
544 */
545 GTlsCertificate *
g_tls_connection_get_certificate(GTlsConnection * conn)546 g_tls_connection_get_certificate (GTlsConnection *conn)
547 {
548 GTlsCertificate *certificate;
549
550 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
551
552 g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
553 if (certificate)
554 g_object_unref (certificate);
555
556 return certificate;
557 }
558
559 /**
560 * g_tls_connection_set_interaction:
561 * @conn: a connection
562 * @interaction: (nullable): an interaction object, or %NULL
563 *
564 * Set the object that will be used to interact with the user. It will be used
565 * for things like prompting the user for passwords.
566 *
567 * The @interaction argument will normally be a derived subclass of
568 * #GTlsInteraction. %NULL can also be provided if no user interaction
569 * should occur for this connection.
570 *
571 * Since: 2.30
572 */
573 void
g_tls_connection_set_interaction(GTlsConnection * conn,GTlsInteraction * interaction)574 g_tls_connection_set_interaction (GTlsConnection *conn,
575 GTlsInteraction *interaction)
576 {
577 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
578 g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
579
580 g_object_set (G_OBJECT (conn), "interaction", interaction, NULL);
581 }
582
583 /**
584 * g_tls_connection_get_interaction:
585 * @conn: a connection
586 *
587 * Get the object that will be used to interact with the user. It will be used
588 * for things like prompting the user for passwords. If %NULL is returned, then
589 * no user interaction will occur for this connection.
590 *
591 * Returns: (transfer none) (nullable): The interaction object.
592 *
593 * Since: 2.30
594 */
595 GTlsInteraction *
g_tls_connection_get_interaction(GTlsConnection * conn)596 g_tls_connection_get_interaction (GTlsConnection *conn)
597 {
598 GTlsInteraction *interaction = NULL;
599
600 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
601
602 g_object_get (G_OBJECT (conn), "interaction", &interaction, NULL);
603 if (interaction)
604 g_object_unref (interaction);
605
606 return interaction;
607 }
608
609 /**
610 * g_tls_connection_get_peer_certificate:
611 * @conn: a #GTlsConnection
612 *
613 * Gets @conn's peer's certificate after the handshake has completed
614 * or failed. (It is not set during the emission of
615 * #GTlsConnection::accept-certificate.)
616 *
617 * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
618 *
619 * Since: 2.28
620 */
621 GTlsCertificate *
g_tls_connection_get_peer_certificate(GTlsConnection * conn)622 g_tls_connection_get_peer_certificate (GTlsConnection *conn)
623 {
624 GTlsCertificate *peer_certificate;
625
626 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
627
628 g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
629 if (peer_certificate)
630 g_object_unref (peer_certificate);
631
632 return peer_certificate;
633 }
634
635 /**
636 * g_tls_connection_get_peer_certificate_errors:
637 * @conn: a #GTlsConnection
638 *
639 * Gets the errors associated with validating @conn's peer's
640 * certificate, after the handshake has completed or failed. (It is
641 * not set during the emission of #GTlsConnection::accept-certificate.)
642 *
643 * Returns: @conn's peer's certificate errors
644 *
645 * Since: 2.28
646 */
647 GTlsCertificateFlags
g_tls_connection_get_peer_certificate_errors(GTlsConnection * conn)648 g_tls_connection_get_peer_certificate_errors (GTlsConnection *conn)
649 {
650 GTlsCertificateFlags errors;
651
652 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), 0);
653
654 g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
655 return errors;
656 }
657
658 /**
659 * g_tls_connection_set_require_close_notify:
660 * @conn: a #GTlsConnection
661 * @require_close_notify: whether or not to require close notification
662 *
663 * Sets whether or not @conn expects a proper TLS close notification
664 * before the connection is closed. If this is %TRUE (the default),
665 * then @conn will expect to receive a TLS close notification from its
666 * peer before the connection is closed, and will return a
667 * %G_TLS_ERROR_EOF error if the connection is closed without proper
668 * notification (since this may indicate a network error, or
669 * man-in-the-middle attack).
670 *
671 * In some protocols, the application will know whether or not the
672 * connection was closed cleanly based on application-level data
673 * (because the application-level data includes a length field, or is
674 * somehow self-delimiting); in this case, the close notify is
675 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
676 * in TLS 1.0 it is technically an error, but often done anyway.) You
677 * can use g_tls_connection_set_require_close_notify() to tell @conn
678 * to allow an "unannounced" connection close, in which case the close
679 * will show up as a 0-length read, as in a non-TLS
680 * #GSocketConnection, and it is up to the application to check that
681 * the data has been fully received.
682 *
683 * Note that this only affects the behavior when the peer closes the
684 * connection; when the application calls g_io_stream_close() itself
685 * on @conn, this will send a close notification regardless of the
686 * setting of this property. If you explicitly want to do an unclean
687 * close, you can close @conn's #GTlsConnection:base-io-stream rather
688 * than closing @conn itself, but note that this may only be done when no other
689 * operations are pending on @conn or the base I/O stream.
690 *
691 * Since: 2.28
692 */
693 void
g_tls_connection_set_require_close_notify(GTlsConnection * conn,gboolean require_close_notify)694 g_tls_connection_set_require_close_notify (GTlsConnection *conn,
695 gboolean require_close_notify)
696 {
697 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
698
699 g_object_set (G_OBJECT (conn),
700 "require-close-notify", require_close_notify,
701 NULL);
702 }
703
704 /**
705 * g_tls_connection_get_require_close_notify:
706 * @conn: a #GTlsConnection
707 *
708 * Tests whether or not @conn expects a proper TLS close notification
709 * when the connection is closed. See
710 * g_tls_connection_set_require_close_notify() for details.
711 *
712 * Returns: %TRUE if @conn requires a proper TLS close
713 * notification.
714 *
715 * Since: 2.28
716 */
717 gboolean
g_tls_connection_get_require_close_notify(GTlsConnection * conn)718 g_tls_connection_get_require_close_notify (GTlsConnection *conn)
719 {
720 gboolean require_close_notify;
721
722 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
723
724 g_object_get (G_OBJECT (conn),
725 "require-close-notify", &require_close_notify,
726 NULL);
727 return require_close_notify;
728 }
729
730 /**
731 * g_tls_connection_set_rehandshake_mode:
732 * @conn: a #GTlsConnection
733 * @mode: the rehandshaking mode
734 *
735 * Since GLib 2.64, changing the rehandshake mode is no longer supported
736 * and will have no effect. With TLS 1.3, rehandshaking has been removed from
737 * the TLS protocol, replaced by separate post-handshake authentication and
738 * rekey operations.
739 *
740 * Since: 2.28
741 *
742 * Deprecated: 2.60. Changing the rehandshake mode is no longer
743 * required for compatibility. Also, rehandshaking has been removed
744 * from the TLS protocol in TLS 1.3.
745 */
746 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
747 void
g_tls_connection_set_rehandshake_mode(GTlsConnection * conn,GTlsRehandshakeMode mode)748 g_tls_connection_set_rehandshake_mode (GTlsConnection *conn,
749 GTlsRehandshakeMode mode)
750 {
751 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
752
753 g_object_set (G_OBJECT (conn),
754 "rehandshake-mode", G_TLS_REHANDSHAKE_SAFELY,
755 NULL);
756 }
757 G_GNUC_END_IGNORE_DEPRECATIONS
758
759 /**
760 * g_tls_connection_get_rehandshake_mode:
761 * @conn: a #GTlsConnection
762 *
763 * Gets @conn rehandshaking mode. See
764 * g_tls_connection_set_rehandshake_mode() for details.
765 *
766 * Returns: %G_TLS_REHANDSHAKE_SAFELY
767 *
768 * Since: 2.28
769 *
770 * Deprecated: 2.60. Changing the rehandshake mode is no longer
771 * required for compatibility. Also, rehandshaking has been removed
772 * from the TLS protocol in TLS 1.3.
773 */
774 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
775 GTlsRehandshakeMode
g_tls_connection_get_rehandshake_mode(GTlsConnection * conn)776 g_tls_connection_get_rehandshake_mode (GTlsConnection *conn)
777 {
778 GTlsRehandshakeMode mode;
779
780 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), G_TLS_REHANDSHAKE_SAFELY);
781
782 /* Continue to call g_object_get(), even though the return value is
783 * ignored, so that behavior doesn’t change for derived classes.
784 */
785 g_object_get (G_OBJECT (conn),
786 "rehandshake-mode", &mode,
787 NULL);
788 return G_TLS_REHANDSHAKE_SAFELY;
789 }
790 G_GNUC_END_IGNORE_DEPRECATIONS
791
792 /**
793 * g_tls_connection_set_advertised_protocols:
794 * @conn: a #GTlsConnection
795 * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
796 * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
797 *
798 * Sets the list of application-layer protocols to advertise that the
799 * caller is willing to speak on this connection. The
800 * Application-Layer Protocol Negotiation (ALPN) extension will be
801 * used to negotiate a compatible protocol with the peer; use
802 * g_tls_connection_get_negotiated_protocol() to find the negotiated
803 * protocol after the handshake. Specifying %NULL for the the value
804 * of @protocols will disable ALPN negotiation.
805 *
806 * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
807 * for a list of registered protocol IDs.
808 *
809 * Since: 2.60
810 */
811 void
g_tls_connection_set_advertised_protocols(GTlsConnection * conn,const gchar * const * protocols)812 g_tls_connection_set_advertised_protocols (GTlsConnection *conn,
813 const gchar * const *protocols)
814 {
815 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
816
817 g_object_set (G_OBJECT (conn),
818 "advertised-protocols", protocols,
819 NULL);
820 }
821
822 /**
823 * g_tls_connection_get_negotiated_protocol:
824 * @conn: a #GTlsConnection
825 *
826 * Gets the name of the application-layer protocol negotiated during
827 * the handshake.
828 *
829 * If the peer did not use the ALPN extension, or did not advertise a
830 * protocol that matched one of @conn's protocols, or the TLS backend
831 * does not support ALPN, then this will be %NULL. See
832 * g_tls_connection_set_advertised_protocols().
833 *
834 * Returns: (nullable): the negotiated protocol, or %NULL
835 *
836 * Since: 2.60
837 */
838 const gchar *
g_tls_connection_get_negotiated_protocol(GTlsConnection * conn)839 g_tls_connection_get_negotiated_protocol (GTlsConnection *conn)
840 {
841 GTlsConnectionPrivate *priv;
842 gchar *protocol;
843
844 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
845
846 g_object_get (G_OBJECT (conn),
847 "negotiated-protocol", &protocol,
848 NULL);
849
850 /*
851 * Cache the property internally so we can return a `const` pointer
852 * to the caller.
853 */
854 priv = g_tls_connection_get_instance_private (conn);
855 if (g_strcmp0 (priv->negotiated_protocol, protocol) != 0)
856 {
857 g_free (priv->negotiated_protocol);
858 priv->negotiated_protocol = protocol;
859 }
860 else
861 {
862 g_free (protocol);
863 }
864
865 return priv->negotiated_protocol;
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
g_tls_connection_get_channel_binding_data(GTlsConnection * conn,GTlsChannelBindingType type,GByteArray * data,GError ** error)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
g_tls_connection_handshake(GTlsConnection * conn,GCancellable * cancellable,GError ** error)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
g_tls_connection_handshake_async(GTlsConnection * conn,int io_priority,GCancellable * cancellable,GAsyncReadyCallback callback,gpointer user_data)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
g_tls_connection_handshake_finish(GTlsConnection * conn,GAsyncResult * result,GError ** error)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_error_quark:
1033 *
1034 * Gets the TLS error quark.
1035 *
1036 * Returns: a #GQuark.
1037 *
1038 * Since: 2.28
1039 */
1040 G_DEFINE_QUARK (g-tls-error-quark, g_tls_error)
1041
1042 /**
1043 * g_tls_connection_emit_accept_certificate:
1044 * @conn: a #GTlsConnection
1045 * @peer_cert: the peer's #GTlsCertificate
1046 * @errors: the problems with @peer_cert
1047 *
1048 * Used by #GTlsConnection implementations to emit the
1049 * #GTlsConnection::accept-certificate signal.
1050 *
1051 * Returns: %TRUE if one of the signal handlers has returned
1052 * %TRUE to accept @peer_cert
1053 *
1054 * Since: 2.28
1055 */
1056 gboolean
g_tls_connection_emit_accept_certificate(GTlsConnection * conn,GTlsCertificate * peer_cert,GTlsCertificateFlags errors)1057 g_tls_connection_emit_accept_certificate (GTlsConnection *conn,
1058 GTlsCertificate *peer_cert,
1059 GTlsCertificateFlags errors)
1060 {
1061 gboolean accept = FALSE;
1062
1063 g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
1064 peer_cert, errors, &accept);
1065 return accept;
1066 }
1067