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 /**
144 * GTlsConnection:database:
145 *
146 * The certificate database to use when verifying this TLS connection.
147 * If no certificate database is set, then the default database will be
148 * used. See g_tls_backend_get_default_database().
149 *
150 * Since: 2.30
151 */
152 g_object_class_install_property (gobject_class, PROP_DATABASE,
153 g_param_spec_object ("database",
154 P_("Database"),
155 P_("Certificate database to use for looking up or verifying certificates"),
156 G_TYPE_TLS_DATABASE,
157 G_PARAM_READWRITE |
158 G_PARAM_STATIC_STRINGS));
159 /**
160 * GTlsConnection:interaction:
161 *
162 * A #GTlsInteraction object to be used when the connection or certificate
163 * database need to interact with the user. This will be used to prompt the
164 * user for passwords where necessary.
165 *
166 * Since: 2.30
167 */
168 g_object_class_install_property (gobject_class, PROP_INTERACTION,
169 g_param_spec_object ("interaction",
170 P_("Interaction"),
171 P_("Optional object for user interaction"),
172 G_TYPE_TLS_INTERACTION,
173 G_PARAM_READWRITE |
174 G_PARAM_STATIC_STRINGS));
175 /**
176 * GTlsConnection:require-close-notify:
177 *
178 * Whether or not proper TLS close notification is required.
179 * See g_tls_connection_set_require_close_notify().
180 *
181 * Since: 2.28
182 */
183 g_object_class_install_property (gobject_class, PROP_REQUIRE_CLOSE_NOTIFY,
184 g_param_spec_boolean ("require-close-notify",
185 P_("Require close notify"),
186 P_("Whether to require proper TLS close notification"),
187 TRUE,
188 G_PARAM_READWRITE |
189 G_PARAM_CONSTRUCT |
190 G_PARAM_STATIC_STRINGS));
191 /**
192 * GTlsConnection:rehandshake-mode:
193 *
194 * The rehandshaking mode. See
195 * g_tls_connection_set_rehandshake_mode().
196 *
197 * Since: 2.28
198 */
199 g_object_class_install_property (gobject_class, PROP_REHANDSHAKE_MODE,
200 g_param_spec_enum ("rehandshake-mode",
201 P_("Rehandshake mode"),
202 P_("When to allow rehandshaking"),
203 G_TYPE_TLS_REHANDSHAKE_MODE,
204 G_TLS_REHANDSHAKE_SAFELY,
205 G_PARAM_READWRITE |
206 G_PARAM_CONSTRUCT |
207 G_PARAM_STATIC_STRINGS |
208 G_PARAM_DEPRECATED));
209 /**
210 * GTlsConnection:certificate:
211 *
212 * The connection's certificate; see
213 * g_tls_connection_set_certificate().
214 *
215 * Since: 2.28
216 */
217 g_object_class_install_property (gobject_class, PROP_CERTIFICATE,
218 g_param_spec_object ("certificate",
219 P_("Certificate"),
220 P_("The connection’s certificate"),
221 G_TYPE_TLS_CERTIFICATE,
222 G_PARAM_READWRITE |
223 G_PARAM_STATIC_STRINGS));
224 /**
225 * GTlsConnection:peer-certificate:
226 *
227 * The connection's peer's certificate, after the TLS handshake has
228 * completed and the certificate has been accepted. Note in
229 * particular that this is not yet set during the emission of
230 * #GTlsConnection::accept-certificate.
231 *
232 * (You can watch for a #GObject::notify signal on this property to
233 * detect when a handshake has occurred.)
234 *
235 * Since: 2.28
236 */
237 g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE,
238 g_param_spec_object ("peer-certificate",
239 P_("Peer Certificate"),
240 P_("The connection’s peer’s certificate"),
241 G_TYPE_TLS_CERTIFICATE,
242 G_PARAM_READABLE |
243 G_PARAM_STATIC_STRINGS));
244 /**
245 * GTlsConnection:peer-certificate-errors:
246 *
247 * The errors noticed-and-ignored while verifying
248 * #GTlsConnection:peer-certificate. Normally this should be 0, but
249 * it may not be if #GTlsClientConnection:validation-flags is not
250 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
251 * #GTlsConnection::accept-certificate overrode the default
252 * behavior.
253 *
254 * Since: 2.28
255 */
256 g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE_ERRORS,
257 g_param_spec_flags ("peer-certificate-errors",
258 P_("Peer Certificate Errors"),
259 P_("Errors found with the peer’s certificate"),
260 G_TYPE_TLS_CERTIFICATE_FLAGS,
261 0,
262 G_PARAM_READABLE |
263 G_PARAM_STATIC_STRINGS));
264 /**
265 * GTlsConnection:advertised-protocols:
266 *
267 * The list of application-layer protocols that the connection
268 * advertises that it is willing to speak. See
269 * g_tls_connection_set_advertised_protocols().
270 *
271 * Since: 2.60
272 */
273 g_object_class_install_property (gobject_class, PROP_ADVERTISED_PROTOCOLS,
274 g_param_spec_boxed ("advertised-protocols",
275 P_("Advertised Protocols"),
276 P_("Application-layer protocols available on this connection"),
277 G_TYPE_STRV,
278 G_PARAM_READWRITE |
279 G_PARAM_STATIC_STRINGS));
280 /**
281 * GTlsConnection:negotiated-protocol:
282 *
283 * The application-layer protocol negotiated during the TLS
284 * handshake. See g_tls_connection_get_negotiated_protocol().
285 *
286 * Since: 2.60
287 */
288 g_object_class_install_property (gobject_class, PROP_NEGOTIATED_PROTOCOL,
289 g_param_spec_string ("negotiated-protocol",
290 P_("Negotiated Protocol"),
291 P_("Application-layer protocol negotiated for this connection"),
292 NULL,
293 G_PARAM_READABLE |
294 G_PARAM_STATIC_STRINGS));
295
296 /**
297 * GTlsConnection::accept-certificate:
298 * @conn: a #GTlsConnection
299 * @peer_cert: the peer's #GTlsCertificate
300 * @errors: the problems with @peer_cert.
301 *
302 * Emitted during the TLS handshake after the peer certificate has
303 * been received. You can examine @peer_cert's certification path by
304 * calling g_tls_certificate_get_issuer() on it.
305 *
306 * For a client-side connection, @peer_cert is the server's
307 * certificate, and the signal will only be emitted if the
308 * certificate was not acceptable according to @conn's
309 * #GTlsClientConnection:validation_flags. If you would like the
310 * certificate to be accepted despite @errors, return %TRUE from the
311 * signal handler. Otherwise, if no handler accepts the certificate,
312 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
313 *
314 * For a server-side connection, @peer_cert is the certificate
315 * presented by the client, if this was requested via the server's
316 * #GTlsServerConnection:authentication_mode. On the server side,
317 * the signal is always emitted when the client presents a
318 * certificate, and the certificate will only be accepted if a
319 * handler returns %TRUE.
320 *
321 * Note that if this signal is emitted as part of asynchronous I/O
322 * in the main thread, then you should not attempt to interact with
323 * the user before returning from the signal handler. If you want to
324 * let the user decide whether or not to accept the certificate, you
325 * would have to return %FALSE from the signal handler on the first
326 * attempt, and then after the connection attempt returns a
327 * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
328 * if the user decides to accept the certificate, remember that fact,
329 * create a new connection, and return %TRUE from the signal handler
330 * the next time.
331 *
332 * If you are doing I/O in another thread, you do not
333 * need to worry about this, and can simply block in the signal
334 * handler until the UI thread returns an answer.
335 *
336 * Returns: %TRUE to accept @peer_cert (which will also
337 * immediately end the signal emission). %FALSE to allow the signal
338 * emission to continue, which will cause the handshake to fail if
339 * no one else overrides it.
340 *
341 * Since: 2.28
342 */
343 signals[ACCEPT_CERTIFICATE] =
344 g_signal_new (I_("accept-certificate"),
345 G_TYPE_TLS_CONNECTION,
346 G_SIGNAL_RUN_LAST,
347 G_STRUCT_OFFSET (GTlsConnectionClass, accept_certificate),
348 g_signal_accumulator_true_handled, NULL,
349 _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGS,
350 G_TYPE_BOOLEAN, 2,
351 G_TYPE_TLS_CERTIFICATE,
352 G_TYPE_TLS_CERTIFICATE_FLAGS);
353 g_signal_set_va_marshaller (signals[ACCEPT_CERTIFICATE],
354 G_TYPE_FROM_CLASS (klass),
355 _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGSv);
356 }
357
358 static void
g_tls_connection_init(GTlsConnection * conn)359 g_tls_connection_init (GTlsConnection *conn)
360 {
361 }
362
363 static void
g_tls_connection_get_property(GObject * object,guint prop_id,GValue * value,GParamSpec * pspec)364 g_tls_connection_get_property (GObject *object,
365 guint prop_id,
366 GValue *value,
367 GParamSpec *pspec)
368 {
369 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
370 }
371
372 static void
g_tls_connection_set_property(GObject * object,guint prop_id,const GValue * value,GParamSpec * pspec)373 g_tls_connection_set_property (GObject *object,
374 guint prop_id,
375 const GValue *value,
376 GParamSpec *pspec)
377 {
378 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
379 }
380
381 static void
g_tls_connection_finalize(GObject * object)382 g_tls_connection_finalize (GObject *object)
383 {
384 GTlsConnection *conn = G_TLS_CONNECTION(object);
385 GTlsConnectionPrivate *priv = g_tls_connection_get_instance_private (conn);
386
387 g_clear_pointer (&priv->negotiated_protocol, g_free);
388
389 G_OBJECT_CLASS (g_tls_connection_parent_class)->finalize (object);
390 }
391
392 /**
393 * g_tls_connection_set_use_system_certdb:
394 * @conn: a #GTlsConnection
395 * @use_system_certdb: whether to use the system certificate database
396 *
397 * Sets whether @conn uses the system certificate database to verify
398 * peer certificates. This is %TRUE by default. If set to %FALSE, then
399 * peer certificate validation will always set the
400 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
401 * #GTlsConnection::accept-certificate will always be emitted on
402 * client-side connections, unless that bit is not set in
403 * #GTlsClientConnection:validation-flags).
404 *
405 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
406 */
407 void
g_tls_connection_set_use_system_certdb(GTlsConnection * conn,gboolean use_system_certdb)408 g_tls_connection_set_use_system_certdb (GTlsConnection *conn,
409 gboolean use_system_certdb)
410 {
411 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
412
413 g_object_set (G_OBJECT (conn),
414 "use-system-certdb", use_system_certdb,
415 NULL);
416 }
417
418 /**
419 * g_tls_connection_get_use_system_certdb:
420 * @conn: a #GTlsConnection
421 *
422 * Gets whether @conn uses the system certificate database to verify
423 * peer certificates. See g_tls_connection_set_use_system_certdb().
424 *
425 * Returns: whether @conn uses the system certificate database
426 *
427 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
428 */
429 gboolean
g_tls_connection_get_use_system_certdb(GTlsConnection * conn)430 g_tls_connection_get_use_system_certdb (GTlsConnection *conn)
431 {
432 gboolean use_system_certdb;
433
434 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
435
436 g_object_get (G_OBJECT (conn),
437 "use-system-certdb", &use_system_certdb,
438 NULL);
439 return use_system_certdb;
440 }
441
442 /**
443 * g_tls_connection_set_database:
444 * @conn: a #GTlsConnection
445 * @database: a #GTlsDatabase
446 *
447 * Sets the certificate database that is used to verify peer certificates.
448 * This is set to the default database by default. See
449 * g_tls_backend_get_default_database(). If set to %NULL, then
450 * peer certificate validation will always set the
451 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
452 * #GTlsConnection::accept-certificate will always be emitted on
453 * client-side connections, unless that bit is not set in
454 * #GTlsClientConnection:validation-flags).
455 *
456 * Since: 2.30
457 */
458 void
g_tls_connection_set_database(GTlsConnection * conn,GTlsDatabase * database)459 g_tls_connection_set_database (GTlsConnection *conn,
460 GTlsDatabase *database)
461 {
462 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
463 g_return_if_fail (database == NULL || G_IS_TLS_DATABASE (database));
464
465 g_object_set (G_OBJECT (conn),
466 "database", database,
467 NULL);
468 }
469
470 /**
471 * g_tls_connection_get_database:
472 * @conn: a #GTlsConnection
473 *
474 * Gets the certificate database that @conn uses to verify
475 * peer certificates. See g_tls_connection_set_database().
476 *
477 * Returns: (transfer none): the certificate database that @conn uses or %NULL
478 *
479 * Since: 2.30
480 */
481 GTlsDatabase*
g_tls_connection_get_database(GTlsConnection * conn)482 g_tls_connection_get_database (GTlsConnection *conn)
483 {
484 GTlsDatabase *database = NULL;
485
486 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
487
488 g_object_get (G_OBJECT (conn),
489 "database", &database,
490 NULL);
491 if (database)
492 g_object_unref (database);
493 return database;
494 }
495
496 /**
497 * g_tls_connection_set_certificate:
498 * @conn: a #GTlsConnection
499 * @certificate: the certificate to use for @conn
500 *
501 * This sets the certificate that @conn will present to its peer
502 * during the TLS handshake. For a #GTlsServerConnection, it is
503 * mandatory to set this, and that will normally be done at construct
504 * time.
505 *
506 * For a #GTlsClientConnection, this is optional. If a handshake fails
507 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
508 * requires a certificate, and if you try connecting again, you should
509 * call this method first. You can call
510 * g_tls_client_connection_get_accepted_cas() on the failed connection
511 * to get a list of Certificate Authorities that the server will
512 * accept certificates from.
513 *
514 * (It is also possible that a server will allow the connection with
515 * or without a certificate; in that case, if you don't provide a
516 * certificate, you can tell that the server requested one by the fact
517 * that g_tls_client_connection_get_accepted_cas() will return
518 * non-%NULL.)
519 *
520 * Since: 2.28
521 */
522 void
g_tls_connection_set_certificate(GTlsConnection * conn,GTlsCertificate * certificate)523 g_tls_connection_set_certificate (GTlsConnection *conn,
524 GTlsCertificate *certificate)
525 {
526 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
527 g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
528
529 g_object_set (G_OBJECT (conn), "certificate", certificate, NULL);
530 }
531
532 /**
533 * g_tls_connection_get_certificate:
534 * @conn: a #GTlsConnection
535 *
536 * Gets @conn's certificate, as set by
537 * g_tls_connection_set_certificate().
538 *
539 * Returns: (transfer none): @conn's certificate, or %NULL
540 *
541 * Since: 2.28
542 */
543 GTlsCertificate *
g_tls_connection_get_certificate(GTlsConnection * conn)544 g_tls_connection_get_certificate (GTlsConnection *conn)
545 {
546 GTlsCertificate *certificate;
547
548 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
549
550 g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
551 if (certificate)
552 g_object_unref (certificate);
553
554 return certificate;
555 }
556
557 /**
558 * g_tls_connection_set_interaction:
559 * @conn: a connection
560 * @interaction: (nullable): an interaction object, or %NULL
561 *
562 * Set the object that will be used to interact with the user. It will be used
563 * for things like prompting the user for passwords.
564 *
565 * The @interaction argument will normally be a derived subclass of
566 * #GTlsInteraction. %NULL can also be provided if no user interaction
567 * should occur for this connection.
568 *
569 * Since: 2.30
570 */
571 void
g_tls_connection_set_interaction(GTlsConnection * conn,GTlsInteraction * interaction)572 g_tls_connection_set_interaction (GTlsConnection *conn,
573 GTlsInteraction *interaction)
574 {
575 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
576 g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
577
578 g_object_set (G_OBJECT (conn), "interaction", interaction, NULL);
579 }
580
581 /**
582 * g_tls_connection_get_interaction:
583 * @conn: a connection
584 *
585 * Get the object that will be used to interact with the user. It will be used
586 * for things like prompting the user for passwords. If %NULL is returned, then
587 * no user interaction will occur for this connection.
588 *
589 * Returns: (transfer none): The interaction object.
590 *
591 * Since: 2.30
592 */
593 GTlsInteraction *
g_tls_connection_get_interaction(GTlsConnection * conn)594 g_tls_connection_get_interaction (GTlsConnection *conn)
595 {
596 GTlsInteraction *interaction = NULL;
597
598 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
599
600 g_object_get (G_OBJECT (conn), "interaction", &interaction, NULL);
601 if (interaction)
602 g_object_unref (interaction);
603
604 return interaction;
605 }
606
607 /**
608 * g_tls_connection_get_peer_certificate:
609 * @conn: a #GTlsConnection
610 *
611 * Gets @conn's peer's certificate after the handshake has completed.
612 * (It is not set during the emission of
613 * #GTlsConnection::accept-certificate.)
614 *
615 * Returns: (transfer none): @conn's peer's certificate, or %NULL
616 *
617 * Since: 2.28
618 */
619 GTlsCertificate *
g_tls_connection_get_peer_certificate(GTlsConnection * conn)620 g_tls_connection_get_peer_certificate (GTlsConnection *conn)
621 {
622 GTlsCertificate *peer_certificate;
623
624 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
625
626 g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
627 if (peer_certificate)
628 g_object_unref (peer_certificate);
629
630 return peer_certificate;
631 }
632
633 /**
634 * g_tls_connection_get_peer_certificate_errors:
635 * @conn: a #GTlsConnection
636 *
637 * Gets the errors associated with validating @conn's peer's
638 * certificate, after the handshake has completed. (It is not set
639 * during the emission of #GTlsConnection::accept-certificate.)
640 *
641 * Returns: @conn's peer's certificate errors
642 *
643 * Since: 2.28
644 */
645 GTlsCertificateFlags
g_tls_connection_get_peer_certificate_errors(GTlsConnection * conn)646 g_tls_connection_get_peer_certificate_errors (GTlsConnection *conn)
647 {
648 GTlsCertificateFlags errors;
649
650 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), 0);
651
652 g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
653 return errors;
654 }
655
656 /**
657 * g_tls_connection_set_require_close_notify:
658 * @conn: a #GTlsConnection
659 * @require_close_notify: whether or not to require close notification
660 *
661 * Sets whether or not @conn expects a proper TLS close notification
662 * before the connection is closed. If this is %TRUE (the default),
663 * then @conn will expect to receive a TLS close notification from its
664 * peer before the connection is closed, and will return a
665 * %G_TLS_ERROR_EOF error if the connection is closed without proper
666 * notification (since this may indicate a network error, or
667 * man-in-the-middle attack).
668 *
669 * In some protocols, the application will know whether or not the
670 * connection was closed cleanly based on application-level data
671 * (because the application-level data includes a length field, or is
672 * somehow self-delimiting); in this case, the close notify is
673 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
674 * in TLS 1.0 it is technically an error, but often done anyway.) You
675 * can use g_tls_connection_set_require_close_notify() to tell @conn
676 * to allow an "unannounced" connection close, in which case the close
677 * will show up as a 0-length read, as in a non-TLS
678 * #GSocketConnection, and it is up to the application to check that
679 * the data has been fully received.
680 *
681 * Note that this only affects the behavior when the peer closes the
682 * connection; when the application calls g_io_stream_close() itself
683 * on @conn, this will send a close notification regardless of the
684 * setting of this property. If you explicitly want to do an unclean
685 * close, you can close @conn's #GTlsConnection:base-io-stream rather
686 * than closing @conn itself, but note that this may only be done when no other
687 * operations are pending on @conn or the base I/O stream.
688 *
689 * Since: 2.28
690 */
691 void
g_tls_connection_set_require_close_notify(GTlsConnection * conn,gboolean require_close_notify)692 g_tls_connection_set_require_close_notify (GTlsConnection *conn,
693 gboolean require_close_notify)
694 {
695 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
696
697 g_object_set (G_OBJECT (conn),
698 "require-close-notify", require_close_notify,
699 NULL);
700 }
701
702 /**
703 * g_tls_connection_get_require_close_notify:
704 * @conn: a #GTlsConnection
705 *
706 * Tests whether or not @conn expects a proper TLS close notification
707 * when the connection is closed. See
708 * g_tls_connection_set_require_close_notify() for details.
709 *
710 * Returns: %TRUE if @conn requires a proper TLS close
711 * notification.
712 *
713 * Since: 2.28
714 */
715 gboolean
g_tls_connection_get_require_close_notify(GTlsConnection * conn)716 g_tls_connection_get_require_close_notify (GTlsConnection *conn)
717 {
718 gboolean require_close_notify;
719
720 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
721
722 g_object_get (G_OBJECT (conn),
723 "require-close-notify", &require_close_notify,
724 NULL);
725 return require_close_notify;
726 }
727
728 /**
729 * g_tls_connection_set_rehandshake_mode:
730 * @conn: a #GTlsConnection
731 * @mode: the rehandshaking mode
732 *
733 * Sets how @conn behaves with respect to rehandshaking requests, when
734 * TLS 1.2 or older is in use.
735 *
736 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
737 * rehandshake after the initial handshake is complete. (For a client,
738 * this means it will refuse rehandshake requests from the server, and
739 * for a server, this means it will close the connection with an error
740 * if the client attempts to rehandshake.)
741 *
742 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
743 * rehandshake only if the other end of the connection supports the
744 * TLS `renegotiation_info` extension. This is the default behavior,
745 * but means that rehandshaking will not work against older
746 * implementations that do not support that extension.
747 *
748 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
749 * rehandshaking even without the `renegotiation_info` extension. On
750 * the server side in particular, this is not recommended, since it
751 * leaves the server open to certain attacks. However, this mode is
752 * necessary if you need to allow renegotiation with older client
753 * software.
754 *
755 * Since: 2.28
756 *
757 * Deprecated: 2.60. Changing the rehandshake mode is no longer
758 * required for compatibility. Also, rehandshaking has been removed
759 * from the TLS protocol in TLS 1.3.
760 */
761 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
762 void
g_tls_connection_set_rehandshake_mode(GTlsConnection * conn,GTlsRehandshakeMode mode)763 g_tls_connection_set_rehandshake_mode (GTlsConnection *conn,
764 GTlsRehandshakeMode mode)
765 {
766 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
767
768 g_object_set (G_OBJECT (conn),
769 "rehandshake-mode", mode,
770 NULL);
771 }
772 G_GNUC_END_IGNORE_DEPRECATIONS
773
774 /**
775 * g_tls_connection_get_rehandshake_mode:
776 * @conn: a #GTlsConnection
777 *
778 * Gets @conn rehandshaking mode. See
779 * g_tls_connection_set_rehandshake_mode() for details.
780 *
781 * Returns: @conn's rehandshaking mode
782 *
783 * Since: 2.28
784 *
785 * Deprecated: 2.60. Changing the rehandshake mode is no longer
786 * required for compatibility. Also, rehandshaking has been removed
787 * from the TLS protocol in TLS 1.3.
788 */
789 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
790 GTlsRehandshakeMode
g_tls_connection_get_rehandshake_mode(GTlsConnection * conn)791 g_tls_connection_get_rehandshake_mode (GTlsConnection *conn)
792 {
793 GTlsRehandshakeMode mode;
794
795 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), G_TLS_REHANDSHAKE_NEVER);
796
797 g_object_get (G_OBJECT (conn),
798 "rehandshake-mode", &mode,
799 NULL);
800 return mode;
801 }
802 G_GNUC_END_IGNORE_DEPRECATIONS
803
804 /**
805 * g_tls_connection_set_advertised_protocols:
806 * @conn: a #GTlsConnection
807 * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
808 * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
809 *
810 * Sets the list of application-layer protocols to advertise that the
811 * caller is willing to speak on this connection. The
812 * Application-Layer Protocol Negotiation (ALPN) extension will be
813 * used to negotiate a compatible protocol with the peer; use
814 * g_tls_connection_get_negotiated_protocol() to find the negotiated
815 * protocol after the handshake. Specifying %NULL for the the value
816 * of @protocols will disable ALPN negotiation.
817 *
818 * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
819 * for a list of registered protocol IDs.
820 *
821 * Since: 2.60
822 */
823 void
g_tls_connection_set_advertised_protocols(GTlsConnection * conn,const gchar * const * protocols)824 g_tls_connection_set_advertised_protocols (GTlsConnection *conn,
825 const gchar * const *protocols)
826 {
827 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
828
829 g_object_set (G_OBJECT (conn),
830 "advertised-protocols", protocols,
831 NULL);
832 }
833
834 /**
835 * g_tls_connection_get_negotiated_protocol:
836 * @conn: a #GTlsConnection
837 *
838 * Gets the name of the application-layer protocol negotiated during
839 * the handshake.
840 *
841 * If the peer did not use the ALPN extension, or did not advertise a
842 * protocol that matched one of @conn's protocols, or the TLS backend
843 * does not support ALPN, then this will be %NULL. See
844 * g_tls_connection_set_advertised_protocols().
845 *
846 * Returns: (nullable): the negotiated protocol, or %NULL
847 *
848 * Since: 2.60
849 */
850 const gchar *
g_tls_connection_get_negotiated_protocol(GTlsConnection * conn)851 g_tls_connection_get_negotiated_protocol (GTlsConnection *conn)
852 {
853 GTlsConnectionPrivate *priv;
854 gchar *protocol;
855
856 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
857
858 g_object_get (G_OBJECT (conn),
859 "negotiated-protocol", &protocol,
860 NULL);
861
862 /*
863 * Cache the property internally so we can return a `const` pointer
864 * to the caller.
865 */
866 priv = g_tls_connection_get_instance_private (conn);
867 if (g_strcmp0 (priv->negotiated_protocol, protocol) != 0)
868 {
869 g_free (priv->negotiated_protocol);
870 priv->negotiated_protocol = protocol;
871 }
872 else
873 {
874 g_free (protocol);
875 }
876
877 return priv->negotiated_protocol;
878 }
879
880 /**
881 * g_tls_connection_handshake:
882 * @conn: a #GTlsConnection
883 * @cancellable: (nullable): a #GCancellable, or %NULL
884 * @error: a #GError, or %NULL
885 *
886 * Attempts a TLS handshake on @conn.
887 *
888 * On the client side, it is never necessary to call this method;
889 * although the connection needs to perform a handshake after
890 * connecting (or after sending a "STARTTLS"-type command) and may
891 * need to rehandshake later if the server requests it,
892 * #GTlsConnection will handle this for you automatically when you try
893 * to send or receive data on the connection. However, you can call
894 * g_tls_connection_handshake() manually if you want to know for sure
895 * whether the initial handshake succeeded or failed (as opposed to
896 * just immediately trying to write to @conn's output stream, in which
897 * case if it fails, it may not be possible to tell if it failed
898 * before or after completing the handshake).
899 *
900 * Likewise, on the server side, although a handshake is necessary at
901 * the beginning of the communication, you do not need to call this
902 * function explicitly unless you want clearer error reporting.
903 *
904 * If TLS 1.2 or older is in use, you may call
905 * g_tls_connection_handshake() after the initial handshake to
906 * rehandshake; however, this usage is deprecated because rehandshaking
907 * is no longer part of the TLS protocol in TLS 1.3. Accordingly, the
908 * behavior of calling this function after the initial handshake is now
909 * undefined, except it is guaranteed to be reasonable and
910 * nondestructive so as to preserve compatibility with code written for
911 * older versions of GLib.
912 *
913 * #GTlsConnection::accept_certificate may be emitted during the
914 * handshake.
915 *
916 * Returns: success or failure
917 *
918 * Since: 2.28
919 */
920 gboolean
g_tls_connection_handshake(GTlsConnection * conn,GCancellable * cancellable,GError ** error)921 g_tls_connection_handshake (GTlsConnection *conn,
922 GCancellable *cancellable,
923 GError **error)
924 {
925 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
926
927 return G_TLS_CONNECTION_GET_CLASS (conn)->handshake (conn, cancellable, error);
928 }
929
930 /**
931 * g_tls_connection_handshake_async:
932 * @conn: a #GTlsConnection
933 * @io_priority: the [I/O priority][io-priority] of the request
934 * @cancellable: (nullable): a #GCancellable, or %NULL
935 * @callback: callback to call when the handshake is complete
936 * @user_data: the data to pass to the callback function
937 *
938 * Asynchronously performs a TLS handshake on @conn. See
939 * g_tls_connection_handshake() for more information.
940 *
941 * Since: 2.28
942 */
943 void
g_tls_connection_handshake_async(GTlsConnection * conn,int io_priority,GCancellable * cancellable,GAsyncReadyCallback callback,gpointer user_data)944 g_tls_connection_handshake_async (GTlsConnection *conn,
945 int io_priority,
946 GCancellable *cancellable,
947 GAsyncReadyCallback callback,
948 gpointer user_data)
949 {
950 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
951
952 G_TLS_CONNECTION_GET_CLASS (conn)->handshake_async (conn, io_priority,
953 cancellable,
954 callback, user_data);
955 }
956
957 /**
958 * g_tls_connection_handshake_finish:
959 * @conn: a #GTlsConnection
960 * @result: a #GAsyncResult.
961 * @error: a #GError pointer, or %NULL
962 *
963 * Finish an asynchronous TLS handshake operation. See
964 * g_tls_connection_handshake() for more information.
965 *
966 * Returns: %TRUE on success, %FALSE on failure, in which
967 * case @error will be set.
968 *
969 * Since: 2.28
970 */
971 gboolean
g_tls_connection_handshake_finish(GTlsConnection * conn,GAsyncResult * result,GError ** error)972 g_tls_connection_handshake_finish (GTlsConnection *conn,
973 GAsyncResult *result,
974 GError **error)
975 {
976 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
977
978 return G_TLS_CONNECTION_GET_CLASS (conn)->handshake_finish (conn, result, error);
979 }
980
981 /**
982 * g_tls_error_quark:
983 *
984 * Gets the TLS error quark.
985 *
986 * Returns: a #GQuark.
987 *
988 * Since: 2.28
989 */
990 G_DEFINE_QUARK (g-tls-error-quark, g_tls_error)
991
992 /**
993 * g_tls_connection_emit_accept_certificate:
994 * @conn: a #GTlsConnection
995 * @peer_cert: the peer's #GTlsCertificate
996 * @errors: the problems with @peer_cert
997 *
998 * Used by #GTlsConnection implementations to emit the
999 * #GTlsConnection::accept-certificate signal.
1000 *
1001 * Returns: %TRUE if one of the signal handlers has returned
1002 * %TRUE to accept @peer_cert
1003 *
1004 * Since: 2.28
1005 */
1006 gboolean
g_tls_connection_emit_accept_certificate(GTlsConnection * conn,GTlsCertificate * peer_cert,GTlsCertificateFlags errors)1007 g_tls_connection_emit_accept_certificate (GTlsConnection *conn,
1008 GTlsCertificate *peer_cert,
1009 GTlsCertificateFlags errors)
1010 {
1011 gboolean accept = FALSE;
1012
1013 g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
1014 peer_cert, errors, &accept);
1015 return accept;
1016 }
1017