1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright © 2010 Red Hat, Inc
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 of the License, or (at your option) any later version.
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.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
24 #include "gtlsconnection.h"
25 #include "gcancellable.h"
26 #include "gioenumtypes.h"
27 #include "gio-marshal.h"
29 #include "gtlsbackend.h"
30 #include "gtlscertificate.h"
31 #include "gtlsclientconnection.h"
35 * SECTION:gtlsconnection
36 * @short_description: TLS connection type
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.
50 * Abstract base class for the backend-specific #GTlsClientConnection
51 * and #GTlsServerConnection types.
56 G_DEFINE_ABSTRACT_TYPE (GTlsConnection, g_tls_connection, G_TYPE_IO_STREAM)
58 static void g_tls_connection_get_property (GObject *object,
62 static void g_tls_connection_set_property (GObject *object,
66 static void g_tls_connection_finalize (GObject *object);
68 static gboolean g_tls_connection_certificate_accumulator (GSignalInvocationHint *ihint,
70 const GValue *handler_return,
80 static guint signals[LAST_SIGNAL] = { 0 };
85 PROP_REQUIRE_CLOSE_NOTIFY,
86 PROP_REHANDSHAKE_MODE,
87 PROP_USE_SYSTEM_CERTDB,
92 struct _GTlsConnectionPrivate {
93 GTlsCertificate *certificate, *peer_certificate;
97 g_tls_connection_class_init (GTlsConnectionClass *klass)
99 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
101 g_type_class_add_private (klass, sizeof (GTlsConnectionPrivate));
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;
108 * GTlsConnection:base-io-stream:
110 * The #GIOStream that the connection wraps
114 g_object_class_install_property (gobject_class, PROP_BASE_IO_STREAM,
115 g_param_spec_object ("base-io-stream",
117 P_("The GIOStream that the connection wraps"),
120 G_PARAM_CONSTRUCT_ONLY |
121 G_PARAM_STATIC_STRINGS));
123 * GTlsConnection:use-system-certdb:
125 * Whether or not the system certificate database will be used to
126 * verify peer certificates. See
127 * g_tls_connection_set_use_system_certdb().
131 g_object_class_install_property (gobject_class, PROP_USE_SYSTEM_CERTDB,
132 g_param_spec_boolean ("use-system-certdb",
133 P_("Use system certificate database"),
134 P_("Whether to verify peer certificates against the system certificate database"),
138 G_PARAM_STATIC_STRINGS));
140 * GTlsConnection:require-close-notify:
142 * Whether or not proper TLS close notification is required.
143 * See g_tls_connection_set_require_close_notify().
147 g_object_class_install_property (gobject_class, PROP_REQUIRE_CLOSE_NOTIFY,
148 g_param_spec_boolean ("require-close-notify",
149 P_("Require close notify"),
150 P_("Whether to require proper TLS close notification"),
154 G_PARAM_STATIC_STRINGS));
156 * GTlsConnection:rehandshake-mode:
158 * The rehandshaking mode. See
159 * g_tls_connection_set_rehandshake_mode().
163 g_object_class_install_property (gobject_class, PROP_REHANDSHAKE_MODE,
164 g_param_spec_enum ("rehandshake-mode",
165 P_("Rehandshake mode"),
166 P_("When to allow rehandshaking"),
167 G_TYPE_TLS_REHANDSHAKE_MODE,
168 G_TLS_REHANDSHAKE_SAFELY,
171 G_PARAM_STATIC_STRINGS));
173 * GTlsConnection:certificate:
175 * The connection's certificate; see
176 * g_tls_connection_set_certificate().
180 g_object_class_install_property (gobject_class, PROP_CERTIFICATE,
181 g_param_spec_object ("certificate",
183 P_("The connection's certificate"),
184 G_TYPE_TLS_CERTIFICATE,
186 G_PARAM_STATIC_STRINGS));
188 * GTlsConnection:peer-certificate:
190 * The connection's peer's certificate, after it has been set during
195 g_object_class_install_property (gobject_class, PROP_PEER_CERTIFICATE,
196 g_param_spec_object ("peer-certificate",
197 P_("Peer Certificate"),
198 P_("The connection's peer's certificate"),
199 G_TYPE_TLS_CERTIFICATE,
201 G_PARAM_STATIC_STRINGS));
204 * GTlsConnection::need-certificate:
205 * @conn: a #GTlsConnection
207 * Emitted during the TLS handshake if a certificate is needed and
208 * one has not been set via g_tls_connection_set_certificate().
210 * For server-side connections, a certificate is always needed, and
211 * the connection will fail if none is provided.
213 * For client-side connections, the signal will be emitted only if
214 * the server has requested a certificate; you can call
215 * g_tls_client_connection_get_accepted_cas() to get a list of
216 * Certificate Authorities that the server will accept certificates
217 * from. If you do not return a certificate (and have not provided
218 * one via g_tls_connection_set_certificate()) then the server may
219 * reject the handshake, in which case the operation will eventually
220 * fail with %G_TLS_ERROR_CERTIFICATE_REQUIRED.
222 * Note that if this signal is emitted as part of asynchronous I/O
223 * in the main thread, then you should not attempt to interact with
224 * the user before returning from the signal handler. If you want to
225 * let the user choose a certificate to return, you would have to
226 * return %NULL from the signal handler on the first attempt, and
227 * then after the connection attempt returns a
228 * %G_TLS_ERROR_CERTIFICATE_REQUIRED, you can interact with the
229 * user, create a new connection, and call
230 * g_tls_connection_set_certificate() on it before handshaking (or
231 * just connect to the signal again and return the certificate the
234 * If you are doing I/O in another thread, you do not
235 * need to worry about this, and can simply block in the signal
236 * handler until the UI thread returns an answer.
238 * Return value: the certificate to send to the peer, or %NULL to
239 * send no certificate. If you return a certificate, the signal
240 * emission will be stopped and further handlers will not be called.
244 signals[NEED_CERTIFICATE] =
245 g_signal_new (I_("need-certificate"),
246 G_TYPE_TLS_CONNECTION,
248 G_STRUCT_OFFSET (GTlsConnectionClass, need_certificate),
249 g_tls_connection_certificate_accumulator, NULL,
250 _gio_marshal_OBJECT__VOID,
251 G_TYPE_TLS_CERTIFICATE, 0);
254 * GTlsConnection::accept-certificate:
255 * @conn: a #GTlsConnection
256 * @peer_cert: the peer's #GTlsCertificate
257 * @errors: the problems with @peer_cert.
259 * Emitted during the TLS handshake after the peer certificate has
260 * been received. You can examine @peer_cert's certification path by
261 * calling g_tls_certificate_get_issuer() on it.
263 * For a client-side connection, @peer_cert is the server's
264 * certificate, and the signal will only be emitted if the
265 * certificate was not acceptable according to @conn's
266 * #GTlsClientConnection:validation_flags. If you would like the
267 * certificate to be accepted despite @errors, return %TRUE from the
268 * signal handler. Otherwise, if no handler accepts the certificate,
269 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
271 * For a server-side connection, @peer_cert is the certificate
272 * presented by the client, if this was requested via the server's
273 * #GTlsServerConnection:authentication_mode. On the server side,
274 * the signal is always emitted when the client presents a
275 * certificate, and the certificate will only be accepted if a
276 * handler returns %TRUE.
278 * As with #GTlsConnection::need_certificate, you should not
279 * interact with the user during the signal emission if the signal
280 * was emitted as part of an asynchronous operation in the main
283 * Return value: %TRUE to accept @peer_cert (which will also
284 * immediately end the signal emission). %FALSE to allow the signal
285 * emission to continue, which will cause the handshake to fail if
286 * no one else overrides it.
290 signals[ACCEPT_CERTIFICATE] =
291 g_signal_new (I_("accept-certificate"),
292 G_TYPE_TLS_CONNECTION,
294 G_STRUCT_OFFSET (GTlsConnectionClass, accept_certificate),
295 g_signal_accumulator_true_handled, NULL,
296 _gio_marshal_BOOLEAN__OBJECT_FLAGS,
298 G_TYPE_TLS_CERTIFICATE,
299 G_TYPE_TLS_CERTIFICATE_FLAGS);
303 g_tls_connection_init (GTlsConnection *conn)
305 conn->priv = G_TYPE_INSTANCE_GET_PRIVATE (conn, G_TYPE_TLS_CONNECTION, GTlsConnectionPrivate);
309 g_tls_connection_finalize (GObject *object)
311 GTlsConnection *conn = G_TLS_CONNECTION (object);
313 if (conn->priv->certificate)
314 g_object_unref (conn->priv->certificate);
315 if (conn->priv->peer_certificate)
316 g_object_unref (conn->priv->peer_certificate);
318 G_OBJECT_CLASS (g_tls_connection_parent_class)->finalize (object);
322 g_tls_connection_get_property (GObject *object,
327 GTlsConnection *conn = G_TLS_CONNECTION (object);
331 case PROP_CERTIFICATE:
332 g_value_set_object (value, conn->priv->certificate);
335 case PROP_PEER_CERTIFICATE:
336 g_value_set_object (value, conn->priv->peer_certificate);
340 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
346 g_tls_connection_set_property (GObject *object,
351 GTlsConnection *conn = G_TLS_CONNECTION (object);
355 case PROP_CERTIFICATE:
356 g_tls_connection_set_certificate (conn, g_value_get_object (value));
360 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
366 * g_tls_connection_set_use_system_certdb:
367 * @conn: a #GTlsConnection
368 * @use_system_certdb: whether to use the system certificate database
370 * Sets whether @conn uses the system certificate database to verify
371 * peer certificates. This is %TRUE by default. If set to %FALSE, then
372 * peer certificate validation will always set the
373 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
374 * #GTlsConnection::accept-certificate will always be emitted on
375 * client-side connections, unless that bit is not set in
376 * #GTlsClientConnection:validation-flags).
381 g_tls_connection_set_use_system_certdb (GTlsConnection *conn,
382 gboolean use_system_certdb)
384 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
386 g_object_set (G_OBJECT (conn),
387 "use-system-certdb", use_system_certdb,
392 * g_tls_connection_get_use_system_certdb:
393 * @conn: a #GTlsConnection
395 * Gets whether @conn uses the system certificate database to verify
396 * peer certificates. See g_tls_connection_set_use_system_certdb().
398 * Return value: whether @conn uses the system certificate database
403 g_tls_connection_get_use_system_certdb (GTlsConnection *conn)
405 gboolean use_system_certdb;
407 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
409 g_object_get (G_OBJECT (conn),
410 "use-system-certdb", &use_system_certdb,
412 return use_system_certdb;
416 * g_tls_connection_set_certificate:
417 * @conn: a #GTlsConnection
418 * @certificate: the certificate to use for @conn
420 * This sets the certificate that @conn will present to its peer
421 * during the TLS handshake. If this is not set,
422 * #GTlsConnection::need-certificate will be emitted during the
423 * handshake if needed.
428 g_tls_connection_set_certificate (GTlsConnection *conn,
429 GTlsCertificate *certificate)
431 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
432 g_return_if_fail (G_IS_TLS_CERTIFICATE (certificate));
434 if (conn->priv->certificate)
435 g_object_unref (conn->priv->certificate);
436 conn->priv->certificate = certificate ? g_object_ref (certificate) : NULL;
437 g_object_notify (G_OBJECT (conn), "certificate");
441 * g_tls_connection_get_certificate:
442 * @conn: a #GTlsConnection
444 * Gets @conn's certificate, as set by
445 * g_tls_connection_set_certificate() or returned from one of the
448 * Return value: @conn's certificate, or %NULL
453 g_tls_connection_get_certificate (GTlsConnection *conn)
455 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
457 return conn->priv->certificate;
461 * g_tls_connection_get_peer_certificate:
462 * @conn: a #GTlsConnection
464 * Gets @conn's peer's certificate after it has been set during the
467 * Return value: @conn's peer's certificate, or %NULL
472 g_tls_connection_get_peer_certificate (GTlsConnection *conn)
474 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), NULL);
476 return conn->priv->peer_certificate;
480 * g_tls_connection_set_require_close_notify:
481 * @conn: a #GTlsConnection
482 * @require_close_notify: whether or not to require close notification
484 * Sets whether or not @conn requires a proper TLS close notification
485 * before closing the connection. If this is %TRUE (the default), then
486 * calling g_io_stream_close() on @conn will send a TLS close
487 * notification, and likewise it will expect to receive a close
488 * notification before the connection is closed when reading, and will
489 * return a %G_TLS_ERROR_EOF error if the connection is closed without
490 * proper notification (since this may indicate a network error, or
491 * man-in-the-middle attack).
493 * In some protocols, the application will know whether or not the
494 * connection was closed cleanly based on application-level data
495 * (because the application-level data includes a length field, or is
496 * somehow self-delimiting); in this case, the close notify is
497 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
498 * in TLS 1.0 it is technically an error, but often done anyway.) You
499 * can use g_tls_connection_set_require_close_notify() to tell @conn to
500 * allow an "unannounced" connection close, in which case it is up to
501 * the application to check that the data has been fully received.
506 g_tls_connection_set_require_close_notify (GTlsConnection *conn,
507 gboolean require_close_notify)
509 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
511 g_object_set (G_OBJECT (conn),
512 "require-close-notify", require_close_notify,
517 * g_tls_connection_get_require_close_notify:
518 * @conn: a #GTlsConnection
520 * Tests whether or not @conn requires a proper TLS close notification
521 * before closing the connection. See
522 * g_tls_connection_set_require_close_notify() for details.
524 * Return value: %TRUE if @conn requires a proper TLS close
530 g_tls_connection_get_require_close_notify (GTlsConnection *conn)
532 gboolean require_close_notify;
534 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), TRUE);
536 g_object_get (G_OBJECT (conn),
537 "require-close-notify", &require_close_notify,
539 return require_close_notify;
543 * g_tls_connection_set_rehandshake_mode:
544 * @conn: a #GTlsConnection
545 * @mode: the rehandshaking mode
547 * Sets how @conn behaves with respect to rehandshaking requests.
549 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
550 * rehandshake after the initial handshake is complete. (For a client,
551 * this means it will refuse rehandshake requests from the server, and
552 * for a server, this means it will close the connection with an error
553 * if the client attempts to rehandshake.)
555 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
556 * rehandshake only if the other end of the connection supports the
557 * TLS <literal>renegotiation_info</literal> extension. This is the
558 * default behavior, but means that rehandshaking will not work
559 * against older implementations that do not support that extension.
561 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
562 * rehandshaking even without the
563 * <literal>renegotiation_info</literal> extension. On the server side
564 * in particular, this is not recommended, since it leaves the server
565 * open to certain attacks. However, this mode is necessary if you
566 * need to allow renegotiation with older client software.
571 g_tls_connection_set_rehandshake_mode (GTlsConnection *conn,
572 GTlsRehandshakeMode mode)
574 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
576 g_object_set (G_OBJECT (conn),
577 "rehandshake-mode", mode,
582 * g_tls_connection_get_rehandshake_mode:
583 * @conn: a #GTlsConnection
585 * Gets @conn rehandshaking mode. See
586 * g_tls_connection_set_rehandshake() for details.
588 * Return value: @conn's rehandshaking mode
593 g_tls_connection_get_rehandshake_mode (GTlsConnection *conn)
595 GTlsRehandshakeMode mode;
597 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), G_TLS_REHANDSHAKE_NEVER);
599 g_object_get (G_OBJECT (conn),
600 "rehandshake-mode", &mode,
606 * g_tls_connection_handshake:
607 * @conn: a #GTlsConnection
608 * @cancellable: a #GCancellable, or %NULL
609 * @error: a #GError, or %NULL
611 * Attempts a TLS handshake on @conn.
613 * On the client side, it is never necessary to call this method;
614 * although the connection needs to perform a handshake after
615 * connecting (or after sending a "STARTTLS"-type command) and may
616 * need to rehandshake later if the server requests it,
617 * #GTlsConnection will handle this for you automatically when you try
618 * to send or receive data on the connection. However, you can call
619 * g_tls_connection_handshake() manually if you want to know for sure
620 * whether the initial handshake succeeded or failed (as opposed to
621 * just immediately trying to write to @conn's output stream, in which
622 * case if it fails, it may not be possible to tell if it failed
623 * before or after completing the handshake).
625 * Likewise, on the server side, although a handshake is necessary at
626 * the beginning of the communication, you do not need to call this
627 * function explicitly unless you want clearer error reporting.
628 * However, you may call g_tls_connection_handshake() later on to
629 * renegotiate parameters (encryption methods, etc) with the client.
631 * #GTlsConnection::accept_certificate and
632 * #GTlsConnection::need_certificate may be emitted during the
635 * Return value: success or failure
640 g_tls_connection_handshake (GTlsConnection *conn,
641 GCancellable *cancellable,
644 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
646 return G_TLS_CONNECTION_GET_CLASS (conn)->handshake (conn, cancellable, error);
650 * g_tls_connection_handshake_async:
651 * @conn: a #GTlsConnection
652 * @io_priority: the <link linkend="io-priority">I/O priority</link>
654 * @cancellable: a #GCancellable, or %NULL
655 * @callback: callback to call when the handshake is complete
656 * @user_data: the data to pass to the callback function
658 * Asynchronously performs a TLS handshake on @conn. See
659 * g_tls_connection_handshake() for more information.
664 g_tls_connection_handshake_async (GTlsConnection *conn,
666 GCancellable *cancellable,
667 GAsyncReadyCallback callback,
670 g_return_if_fail (G_IS_TLS_CONNECTION (conn));
672 return G_TLS_CONNECTION_GET_CLASS (conn)->handshake_async (conn, io_priority,
674 callback, user_data);
678 * g_tls_connection_handshake_finish:
679 * @conn: a #GTlsConnection
680 * @result: a #GAsyncResult.
681 * @error: a #GError pointer, or %NULL
683 * Finish an asynchronous TLS handshake operation. See
684 * g_tls_connection_handshake() for more information.
686 * Return value: %TRUE on success, %FALSE on failure, in which
687 * case @error will be set.
692 g_tls_connection_handshake_finish (GTlsConnection *conn,
693 GAsyncResult *result,
696 g_return_val_if_fail (G_IS_TLS_CONNECTION (conn), FALSE);
698 return G_TLS_CONNECTION_GET_CLASS (conn)->handshake_finish (conn, result, error);
704 * Gets the TLS error quark.
706 * Return value: a #GQuark.
711 g_tls_error_quark (void)
713 return g_quark_from_static_string ("g-tls-error-quark");
718 g_tls_connection_certificate_accumulator (GSignalInvocationHint *ihint,
720 const GValue *handler_return,
723 GTlsCertificate *cert;
725 cert = g_value_get_object (handler_return);
727 g_value_set_object (return_accu, cert);
733 * g_tls_connection_emit_need_certificate:
734 * @conn: a #GTlsConnection
736 * Used by #GTlsConnection implementations to emit the
737 * #GTlsConnection::need-certificate signal.
739 * Returns: a new #GTlsCertificate
744 g_tls_connection_emit_need_certificate (GTlsConnection *conn)
746 GTlsCertificate *cert = NULL;
748 g_signal_emit (conn, signals[NEED_CERTIFICATE], 0,
754 * g_tls_connection_emit_accept_certificate:
755 * @conn: a #GTlsConnection
756 * @peer_cert: the peer's #GTlsCertificate
757 * @errors: the problems with @peer_cert
759 * Used by #GTlsConnection implementations to emit the
760 * #GTlsConnection::accept-certificate signal.
762 * Return value: %TRUE if one of the signal handlers has returned
763 * %TRUE to accept @peer_cert
768 g_tls_connection_emit_accept_certificate (GTlsConnection *conn,
769 GTlsCertificate *peer_cert,
770 GTlsCertificateFlags errors)
772 gboolean accept = FALSE;
774 g_signal_emit (conn, signals[ACCEPT_CERTIFICATE], 0,
775 peer_cert, errors, &accept);
780 * g_tls_connection_set_peer_certificate:
781 * @conn: a #GTlsConnection
782 * @certificate: the peer certificate
784 * Used by #GTlsConnection implementations to set the connection's
790 g_tls_connection_set_peer_certificate (GTlsConnection *conn,
791 GTlsCertificate *certificate)
793 if (conn->priv->peer_certificate)
794 g_object_unref (conn->priv->peer_certificate);
795 conn->priv->peer_certificate = certificate ? g_object_ref (certificate) : NULL;
796 g_object_notify (G_OBJECT (conn), "peer-certificate");