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