Coverage Report

Created: 2025-07-01 07:09

/src/glib/gio/gtlsconnection.c
Line
Count
Source (jump to first uncovered line)
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
99
g_tls_connection_class_init (GTlsConnectionClass *klass)
100
0
{
101
0
  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
102
103
0
  gobject_class->get_property = g_tls_connection_get_property;
104
0
  gobject_class->set_property = g_tls_connection_set_property;
105
0
  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
0
  g_object_class_install_property (gobject_class, PROP_BASE_IO_STREAM,
119
0
           g_param_spec_object ("base-io-stream",
120
0
              P_("Base IOStream"),
121
0
              P_("The GIOStream that the connection wraps"),
122
0
              G_TYPE_IO_STREAM,
123
0
              G_PARAM_READWRITE |
124
0
              G_PARAM_CONSTRUCT_ONLY |
125
0
              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
0
  g_object_class_install_property (gobject_class, PROP_USE_SYSTEM_CERTDB,
136
0
           g_param_spec_boolean ("use-system-certdb",
137
0
               P_("Use system certificate database"),
138
0
               P_("Whether to verify peer certificates against the system certificate database"),
139
0
               TRUE,
140
0
               G_PARAM_READWRITE |
141
0
               G_PARAM_CONSTRUCT |
142
0
               G_PARAM_STATIC_STRINGS |
143
0
               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
0
  g_object_class_install_property (gobject_class, PROP_DATABASE,
154
0
           g_param_spec_object ("database",
155
0
               P_("Database"),
156
0
               P_("Certificate database to use for looking up or verifying certificates"),
157
0
               G_TYPE_TLS_DATABASE,
158
0
               G_PARAM_READWRITE |
159
0
               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
0
  g_object_class_install_property (gobject_class, PROP_INTERACTION,
170
0
                                   g_param_spec_object ("interaction",
171
0
                                                        P_("Interaction"),
172
0
                                                        P_("Optional object for user interaction"),
173
0
                                                        G_TYPE_TLS_INTERACTION,
174
0
                                                        G_PARAM_READWRITE |
175
0
                                                        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
0
  g_object_class_install_property (gobject_class, PROP_REQUIRE_CLOSE_NOTIFY,
185
0
           g_param_spec_boolean ("require-close-notify",
186
0
               P_("Require close notify"),
187
0
               P_("Whether to require proper TLS close notification"),
188
0
               TRUE,
189
0
               G_PARAM_READWRITE |
190
0
               G_PARAM_CONSTRUCT |
191
0
               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
0
  g_object_class_install_property (gobject_class, PROP_REHANDSHAKE_MODE,
203
0
           g_param_spec_enum ("rehandshake-mode",
204
0
                  P_("Rehandshake mode"),
205
0
                  P_("When to allow rehandshaking"),
206
0
                  G_TYPE_TLS_REHANDSHAKE_MODE,
207
0
                  G_TLS_REHANDSHAKE_SAFELY,
208
0
                  G_PARAM_READWRITE |
209
0
                  G_PARAM_CONSTRUCT |
210
0
                  G_PARAM_STATIC_STRINGS |
211
0
                  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
0
  g_object_class_install_property (gobject_class, PROP_CERTIFICATE,
221
0
           g_param_spec_object ("certificate",
222
0
              P_("Certificate"),
223
0
              P_("The connection’s certificate"),
224
0
              G_TYPE_TLS_CERTIFICATE,
225
0
              G_PARAM_READWRITE |
226
0
              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
0
  g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE,
240
0
           g_param_spec_object ("peer-certificate",
241
0
              P_("Peer Certificate"),
242
0
              P_("The connection’s peer’s certificate"),
243
0
              G_TYPE_TLS_CERTIFICATE,
244
0
              G_PARAM_READABLE |
245
0
              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
0
  g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE_ERRORS,
259
0
           g_param_spec_flags ("peer-certificate-errors",
260
0
                   P_("Peer Certificate Errors"),
261
0
                   P_("Errors found with the peer’s certificate"),
262
0
                   G_TYPE_TLS_CERTIFICATE_FLAGS,
263
0
                   0,
264
0
                   G_PARAM_READABLE |
265
0
                   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
0
  g_object_class_install_property (gobject_class, PROP_ADVERTISED_PROTOCOLS,
276
0
                                   g_param_spec_boxed ("advertised-protocols",
277
0
                                                       P_("Advertised Protocols"),
278
0
                                                       P_("Application-layer protocols available on this connection"),
279
0
                                                       G_TYPE_STRV,
280
0
                                                       G_PARAM_READWRITE |
281
0
                                                       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
0
  g_object_class_install_property (gobject_class, PROP_NEGOTIATED_PROTOCOL,
291
0
                                   g_param_spec_string ("negotiated-protocol",
292
0
                                                        P_("Negotiated Protocol"),
293
0
                                                        P_("Application-layer protocol negotiated for this connection"),
294
0
                                                        NULL,
295
0
                                                        G_PARAM_READABLE |
296
0
                                                        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
0
  signals[ACCEPT_CERTIFICATE] =
346
0
    g_signal_new (I_("accept-certificate"),
347
0
      G_TYPE_TLS_CONNECTION,
348
0
      G_SIGNAL_RUN_LAST,
349
0
      G_STRUCT_OFFSET (GTlsConnectionClass, accept_certificate),
350
0
      g_signal_accumulator_true_handled, NULL,
351
0
      _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGS,
352
0
      G_TYPE_BOOLEAN, 2,
353
0
      G_TYPE_TLS_CERTIFICATE,
354
0
      G_TYPE_TLS_CERTIFICATE_FLAGS);
355
0
  g_signal_set_va_marshaller (signals[ACCEPT_CERTIFICATE],
356
0
                              G_TYPE_FROM_CLASS (klass),
357
0
                              _g_cclosure_marshal_BOOLEAN__OBJECT_FLAGSv);
358
0
}
359
360
static void
361
g_tls_connection_init (GTlsConnection *conn)
362
0
{
363
0
}
364
365
static void
366
g_tls_connection_get_property (GObject    *object,
367
             guint       prop_id,
368
             GValue     *value,
369
             GParamSpec *pspec)
370
0
{
371
0
  G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
372
0
}
373
374
static void
375
g_tls_connection_set_property (GObject      *object,
376
             guint         prop_id,
377
             const GValue *value,
378
             GParamSpec   *pspec)
379
0
{
380
0
  G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
381
0
}
382
383
static void
384
g_tls_connection_finalize (GObject *object)
385
0
{
386
0
  GTlsConnection *conn = G_TLS_CONNECTION(object);
387
0
  GTlsConnectionPrivate *priv = g_tls_connection_get_instance_private (conn);
388
389
0
  g_clear_pointer (&priv->negotiated_protocol, g_free);
390
391
0
  G_OBJECT_CLASS (g_tls_connection_parent_class)->finalize (object);
392
0
}
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
410
g_tls_connection_set_use_system_certdb (GTlsConnection *conn,
411
          gboolean        use_system_certdb)
412
0
{
413
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
414
415
0
  g_object_set (G_OBJECT (conn),
416
0
    "use-system-certdb", use_system_certdb,
417
0
    NULL);
418
0
}
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
432
g_tls_connection_get_use_system_certdb (GTlsConnection *conn)
433
0
{
434
0
  gboolean use_system_certdb;
435
436
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
437
438
0
  g_object_get (G_OBJECT (conn),
439
0
    "use-system-certdb", &use_system_certdb,
440
0
    NULL);
441
0
  return use_system_certdb;
442
0
}
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
461
g_tls_connection_set_database (GTlsConnection *conn,
462
                               GTlsDatabase   *database)
463
0
{
464
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
465
0
  g_return_if_fail (database == NULL || G_IS_TLS_DATABASE (database));
466
467
0
  g_object_set (G_OBJECT (conn),
468
0
    "database", database,
469
0
    NULL);
470
0
}
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*
484
g_tls_connection_get_database (GTlsConnection *conn)
485
0
{
486
0
  GTlsDatabase *database = NULL;
487
488
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
489
490
0
  g_object_get (G_OBJECT (conn),
491
0
    "database", &database,
492
0
    NULL);
493
0
  if (database)
494
0
    g_object_unref (database);
495
0
  return database;
496
0
}
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
525
g_tls_connection_set_certificate (GTlsConnection  *conn,
526
          GTlsCertificate *certificate)
527
0
{
528
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
529
0
  g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
530
531
0
  g_object_set (G_OBJECT (conn), "certificate", certificate, NULL);
532
0
}
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 *
546
g_tls_connection_get_certificate (GTlsConnection *conn)
547
0
{
548
0
  GTlsCertificate *certificate;
549
550
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
551
552
0
  g_object_get (G_OBJECT (conn), "certificate", &certificate, NULL);
553
0
  if (certificate)
554
0
    g_object_unref (certificate);
555
556
0
  return certificate;
557
0
}
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
574
g_tls_connection_set_interaction (GTlsConnection       *conn,
575
                                  GTlsInteraction      *interaction)
576
0
{
577
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
578
0
  g_return_if_fail (interaction == NULL || G_IS_TLS_INTERACTION (interaction));
579
580
0
  g_object_set (G_OBJECT (conn), "interaction", interaction, NULL);
581
0
}
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 *
596
g_tls_connection_get_interaction (GTlsConnection       *conn)
597
0
{
598
0
  GTlsInteraction *interaction = NULL;
599
600
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
601
602
0
  g_object_get (G_OBJECT (conn), "interaction", &interaction, NULL);
603
0
  if (interaction)
604
0
    g_object_unref (interaction);
605
606
0
  return interaction;
607
0
}
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 *
622
g_tls_connection_get_peer_certificate (GTlsConnection *conn)
623
0
{
624
0
  GTlsCertificate *peer_certificate;
625
626
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
627
628
0
  g_object_get (G_OBJECT (conn), "peer-certificate", &peer_certificate, NULL);
629
0
  if (peer_certificate)
630
0
    g_object_unref (peer_certificate);
631
632
0
  return peer_certificate;
633
0
}
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
648
g_tls_connection_get_peer_certificate_errors (GTlsConnection *conn)
649
0
{
650
0
  GTlsCertificateFlags errors;
651
652
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), 0);
653
654
0
  g_object_get (G_OBJECT (conn), "peer-certificate-errors", &errors, NULL);
655
0
  return errors;
656
0
}
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
694
g_tls_connection_set_require_close_notify (GTlsConnection *conn,
695
             gboolean        require_close_notify)
696
0
{
697
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
698
699
0
  g_object_set (G_OBJECT (conn),
700
0
    "require-close-notify", require_close_notify,
701
0
    NULL);
702
0
}
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
718
g_tls_connection_get_require_close_notify (GTlsConnection *conn)
719
0
{
720
0
  gboolean require_close_notify;
721
722
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
723
724
0
  g_object_get (G_OBJECT (conn),
725
0
    "require-close-notify", &require_close_notify,
726
0
    NULL);
727
0
  return require_close_notify;
728
0
}
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
748
g_tls_connection_set_rehandshake_mode (GTlsConnection       *conn,
749
               GTlsRehandshakeMode   mode)
750
0
{
751
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
752
753
0
  g_object_set (G_OBJECT (conn),
754
0
    "rehandshake-mode", G_TLS_REHANDSHAKE_SAFELY,
755
0
    NULL);
756
0
}
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
776
g_tls_connection_get_rehandshake_mode (GTlsConnection       *conn)
777
0
{
778
0
  GTlsRehandshakeMode mode;
779
780
0
  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
0
  g_object_get (G_OBJECT (conn),
786
0
    "rehandshake-mode", &mode,
787
0
    NULL);
788
0
  return G_TLS_REHANDSHAKE_SAFELY;
789
0
}
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
812
g_tls_connection_set_advertised_protocols (GTlsConnection      *conn,
813
                                           const gchar * const *protocols)
814
0
{
815
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
816
817
0
  g_object_set (G_OBJECT (conn),
818
0
                "advertised-protocols", protocols,
819
0
                NULL);
820
0
}
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 *
839
g_tls_connection_get_negotiated_protocol (GTlsConnection *conn)
840
0
{
841
0
  GTlsConnectionPrivate *priv;
842
0
  gchar *protocol;
843
844
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
845
846
0
  g_object_get (G_OBJECT (conn),
847
0
                "negotiated-protocol", &protocol,
848
0
                NULL);
849
850
  /*
851
   * Cache the property internally so we can return a `const` pointer
852
   * to the caller.
853
   */
854
0
  priv = g_tls_connection_get_instance_private (conn);
855
0
  if (g_strcmp0 (priv->negotiated_protocol, protocol) != 0)
856
0
    {
857
0
      g_free (priv->negotiated_protocol);
858
0
      priv->negotiated_protocol = protocol;
859
0
    }
860
0
  else
861
0
    {
862
0
      g_free (protocol);
863
0
    }
864
865
0
  return priv->negotiated_protocol;
866
0
}
867
868
/**
869
 * g_tls_channel_binding_error_quark:
870
 *
871
 * Gets the TLS channel binding error quark.
872
 *
873
 * Returns: a #GQuark.
874
 *
875
 * Since: 2.66
876
 */
877
G_DEFINE_QUARK (g-tls-channel-binding-error-quark, g_tls_channel_binding_error)
878
879
/**
880
 * g_tls_connection_get_channel_binding_data:
881
 * @conn: a #GTlsConnection
882
 * @type: #GTlsChannelBindingType type of data to fetch
883
 * @data: (out callee-allocates)(optional)(transfer none): #GByteArray is
884
 *        filled with the binding data, or %NULL
885
 * @error: a #GError pointer, or %NULL
886
 *
887
 * Query the TLS backend for TLS channel binding data of @type for @conn.
888
 *
889
 * This call retrieves TLS channel binding data as specified in RFC
890
 * [5056](https://tools.ietf.org/html/rfc5056), RFC
891
 * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs.  The
892
 * binding data is returned in @data.  The @data is resized by the callee
893
 * using #GByteArray buffer management and will be freed when the @data
894
 * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only
895
 * check whether TLS backend is able to fetch the data (e.g. whether @type
896
 * is supported by the TLS backend). It does not guarantee that the data
897
 * will be available though.  That could happen if TLS connection does not
898
 * support @type or the binding data is not available yet due to additional
899
 * negotiation or input required.
900
 *
901
 * Returns: %TRUE on success, %FALSE otherwise
902
 *
903
 * Since: 2.66
904
 */
905
gboolean
906
g_tls_connection_get_channel_binding_data (GTlsConnection          *conn,
907
                                           GTlsChannelBindingType   type,
908
                                           GByteArray              *data,
909
                                           GError                 **error)
910
0
{
911
0
  GTlsConnectionClass *class;
912
913
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
914
0
  g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
915
916
0
  class = G_TLS_CONNECTION_GET_CLASS (conn);
917
0
  if (class->get_binding_data == NULL)
918
0
    {
919
0
      g_set_error_literal (error, G_TLS_CHANNEL_BINDING_ERROR,
920
0
          G_TLS_CHANNEL_BINDING_ERROR_NOT_IMPLEMENTED,
921
0
          _("TLS backend does not implement TLS binding retrieval"));
922
0
      return FALSE;
923
0
    }
924
925
0
  return class->get_binding_data (conn, type, data, error);
926
0
}
927
928
/**
929
 * g_tls_connection_handshake:
930
 * @conn: a #GTlsConnection
931
 * @cancellable: (nullable): a #GCancellable, or %NULL
932
 * @error: a #GError, or %NULL
933
 *
934
 * Attempts a TLS handshake on @conn.
935
 *
936
 * On the client side, it is never necessary to call this method;
937
 * although the connection needs to perform a handshake after
938
 * connecting (or after sending a "STARTTLS"-type command),
939
 * #GTlsConnection will handle this for you automatically when you try
940
 * to send or receive data on the connection. You can call
941
 * g_tls_connection_handshake() manually if you want to know whether
942
 * the initial handshake succeeded or failed (as opposed to just
943
 * immediately trying to use @conn to read or write, in which case,
944
 * if it fails, it may not be possible to tell if it failed before or
945
 * after completing the handshake), but beware that servers may reject
946
 * client authentication after the handshake has completed, so a
947
 * successful handshake does not indicate the connection will be usable.
948
 *
949
 * Likewise, on the server side, although a handshake is necessary at
950
 * the beginning of the communication, you do not need to call this
951
 * function explicitly unless you want clearer error reporting.
952
 *
953
 * Previously, calling g_tls_connection_handshake() after the initial
954
 * handshake would trigger a rehandshake; however, this usage was
955
 * deprecated in GLib 2.60 because rehandshaking was removed from the
956
 * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
957
 * the initial handshake will no longer do anything.
958
 *
959
 * When using a #GTlsConnection created by #GSocketClient, the
960
 * #GSocketClient performs the initial handshake, so calling this
961
 * function manually is not recommended.
962
 *
963
 * #GTlsConnection::accept_certificate may be emitted during the
964
 * handshake.
965
 *
966
 * Returns: success or failure
967
 *
968
 * Since: 2.28
969
 */
970
gboolean
971
g_tls_connection_handshake (GTlsConnection   *conn,
972
          GCancellable     *cancellable,
973
          GError          **error)
974
0
{
975
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
976
977
0
  return G_TLS_CONNECTION_GET_CLASS (conn)->handshake (conn, cancellable, error);
978
0
}
979
980
/**
981
 * g_tls_connection_handshake_async:
982
 * @conn: a #GTlsConnection
983
 * @io_priority: the [I/O priority][io-priority] of the request
984
 * @cancellable: (nullable): a #GCancellable, or %NULL
985
 * @callback: callback to call when the handshake is complete
986
 * @user_data: the data to pass to the callback function
987
 *
988
 * Asynchronously performs a TLS handshake on @conn. See
989
 * g_tls_connection_handshake() for more information.
990
 *
991
 * Since: 2.28
992
 */
993
void
994
g_tls_connection_handshake_async (GTlsConnection       *conn,
995
          int                   io_priority,
996
          GCancellable         *cancellable,
997
          GAsyncReadyCallback   callback,
998
          gpointer              user_data)
999
0
{
1000
0
  g_return_if_fail (G_IS_TLS_CONNECTION (conn));
1001
1002
0
  G_TLS_CONNECTION_GET_CLASS (conn)->handshake_async (conn, io_priority,
1003
0
                  cancellable,
1004
0
                  callback, user_data);
1005
0
}
1006
1007
/**
1008
 * g_tls_connection_handshake_finish:
1009
 * @conn: a #GTlsConnection
1010
 * @result: a #GAsyncResult.
1011
 * @error: a #GError pointer, or %NULL
1012
 *
1013
 * Finish an asynchronous TLS handshake operation. See
1014
 * g_tls_connection_handshake() for more information.
1015
 *
1016
 * Returns: %TRUE on success, %FALSE on failure, in which
1017
 * case @error will be set.
1018
 *
1019
 * Since: 2.28
1020
 */
1021
gboolean
1022
g_tls_connection_handshake_finish (GTlsConnection  *conn,
1023
           GAsyncResult    *result,
1024
           GError         **error)
1025
0
{
1026
0
  g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
1027
1028
0
  return G_TLS_CONNECTION_GET_CLASS (conn)->handshake_finish (conn, result, error);
1029
0
}
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
1057
g_tls_connection_emit_accept_certificate (GTlsConnection       *conn,
1058
            GTlsCertificate      *peer_cert,
1059
            GTlsCertificateFlags  errors)
1060
0
{
1061
0
  gboolean accept = FALSE;
1062
1063
0
  g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
1064
0
     peer_cert, errors, &accept);
1065
0
  return accept;
1066
0
}