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