TLS Overview

TLS Overview — TLS (aka SSL) support for GSocketConnection

Types and Values

#define	G_TLS_ERROR
enum	GTlsError
#define	G_TLS_CHANNEL_BINDING_ERROR
enum	GTlsChannelBindingError
enum	GTlsAuthenticationMode
enum	GTlsCertificateFlags
enum	GTlsProtocolVersion

Object Hierarchy

    GEnum
    ├── GTlsAuthenticationMode
    ├── GTlsChannelBindingError
    ├── GTlsError
    ╰── GTlsProtocolVersion
    GFlags
    ╰── GTlsCertificateFlags

Includes

#include <gio/gio.h>

Description

GTlsConnection and related classes provide TLS (Transport Layer Security, previously known as SSL, Secure Sockets Layer) support for gio-based network streams.

GDtlsConnection and related classes provide DTLS (Datagram TLS) support for GIO-based network sockets, using the GDatagramBased interface. The TLS and DTLS APIs are almost identical, except TLS is stream-based and DTLS is datagram-based. They share certificate and backend infrastructure.

In the simplest case, for a client TLS connection, you can just set the “tls” flag on a GSocketClient, and then any connections created by that client will have TLS negotiated automatically, using appropriate default settings, and rejecting any invalid or self-signed certificates (unless you change that default by setting the “tls-validation-flags” property). The returned object will be a GTcpWrapperConnection, which wraps the underlying GTlsClientConnection.

For greater control, you can create your own GTlsClientConnection, wrapping a GSocketConnection (or an arbitrary GIOStream with pollable input and output streams) and then connect to its signals, such as “accept-certificate”, before starting the handshake.

Server-side TLS is similar, using GTlsServerConnection. At the moment, there is no support for automatically wrapping server-side connections in the way GSocketClient does for client-side connections.

Functions

Types and Values

G_TLS_ERROR

#define G_TLS_ERROR (g_tls_error_quark ())

Error domain for TLS. Errors in this domain will be from the GTlsError enumeration. See GError for more information on error domains.

enum GTlsError

An error code used with G_TLS_ERROR in a GError returned from a TLS-related routine.

Members

G_TLS_ERROR_UNAVAILABLE	No TLS provider is available
G_TLS_ERROR_MISC	Miscellaneous TLS error
G_TLS_ERROR_BAD_CERTIFICATE	The certificate presented could not be parsed or failed validation.
G_TLS_ERROR_NOT_TLS	The TLS handshake failed because the peer does not seem to be a TLS server.
G_TLS_ERROR_HANDSHAKE	The TLS handshake failed because the peer's certificate was not acceptable.
G_TLS_ERROR_CERTIFICATE_REQUIRED	The TLS handshake failed because the server requested a client-side certificate, but none was provided. See `g_tls_connection_set_certificate()`.
G_TLS_ERROR_EOF	The TLS connection was closed without proper notice, which may indicate an attack. See `g_tls_connection_set_require_close_notify()`.
G_TLS_ERROR_INAPPROPRIATE_FALLBACK	The TLS handshake failed because the client sent the fallback SCSV, indicating a protocol downgrade attack. Since: 2.60

Since: 2.28

G_TLS_CHANNEL_BINDING_ERROR

#define G_TLS_CHANNEL_BINDING_ERROR (g_tls_channel_binding_error_quark ())

Error domain for TLS channel binding. Errors in this domain will be from the GTlsChannelBindingError enumeration. See GError for more information on error domains.

Since: 2.66

enum GTlsChannelBindingError

An error code used with G_TLS_CHANNEL_BINDING_ERROR in a GError to indicate a TLS channel binding retrieval error.

Members

G_TLS_CHANNEL_BINDING_ERROR_NOT_IMPLEMENTED	Either entire binding retrieval facility or specific binding type is not implemented in the TLS backend.
G_TLS_CHANNEL_BINDING_ERROR_INVALID_STATE	The handshake is not yet complete on the connection which is a strong requirement for any existing binding type.
G_TLS_CHANNEL_BINDING_ERROR_NOT_AVAILABLE	Handshake is complete but binding data is not available. That normally indicates the TLS implementation failed to provide the binding data. For example, some implementations do not provide a peer certificate for resumed connections.
G_TLS_CHANNEL_BINDING_ERROR_NOT_SUPPORTED	Binding type is not supported on the current connection. This error could be triggered when requesting `tls-server-end-point` binding data for a certificate which has no hash function or uses multiple hash functions.
G_TLS_CHANNEL_BINDING_ERROR_GENERAL_ERROR	Any other backend error preventing binding data retrieval.

Since: 2.66

enum GTlsAuthenticationMode

The client authentication mode for a GTlsServerConnection.

Members

G_TLS_AUTHENTICATION_NONE	client authentication not required
G_TLS_AUTHENTICATION_REQUESTED	client authentication is requested
G_TLS_AUTHENTICATION_REQUIRED	client authentication is required

Since: 2.28

enum GTlsCertificateFlags

A set of flags describing TLS certification validation. This can be used to set which validation steps to perform (eg, with g_tls_client_connection_set_validation_flags()), or to describe why a particular certificate was rejected (eg, in “accept-certificate”).

Members

G_TLS_CERTIFICATE_UNKNOWN_CA	The signing certificate authority is not known.
G_TLS_CERTIFICATE_BAD_IDENTITY	The certificate does not match the expected identity of the site that it was retrieved from.
G_TLS_CERTIFICATE_NOT_ACTIVATED	The certificate's activation time is still in the future
G_TLS_CERTIFICATE_EXPIRED	The certificate has expired
G_TLS_CERTIFICATE_REVOKED	The certificate has been revoked according to the GTlsConnection's certificate revocation list.
G_TLS_CERTIFICATE_INSECURE	The certificate's algorithm is considered insecure.
G_TLS_CERTIFICATE_GENERIC_ERROR	Some other error occurred validating the certificate
G_TLS_CERTIFICATE_VALIDATE_ALL	the combination of all of the above flags

Since: 2.28

enum GTlsProtocolVersion

The TLS or DTLS protocol version used by a GTlsConnection or GDtlsConnection. The integer values of these versions are sequential to ensure newer known protocol versions compare greater than older known versions. Any known DTLS protocol version will compare greater than any SSL or TLS protocol version. The protocol version may be G_TLS_PROTOCOL_VERSION_UNKNOWN if the TLS backend supports a newer protocol version that GLib does not yet know about. This means that it's possible for an unknown DTLS protocol version to compare less than the TLS protocol versions.

Members

G_TLS_PROTOCOL_VERSION_UNKNOWN	No protocol version or unknown protocol version
G_TLS_PROTOCOL_VERSION_SSL_3_0	SSL 3.0, which is insecure and should not be used
G_TLS_PROTOCOL_VERSION_TLS_1_0	TLS 1.0, which is insecure and should not be used
G_TLS_PROTOCOL_VERSION_TLS_1_1	TLS 1.1, which is insecure and should not be used
G_TLS_PROTOCOL_VERSION_TLS_1_2	TLS 1.2, defined by RFC 5246
G_TLS_PROTOCOL_VERSION_TLS_1_3	TLS 1.3, defined by RFC 8446
G_TLS_PROTOCOL_VERSION_DTLS_1_0	DTLS 1.0, which is insecure and should not be used
G_TLS_PROTOCOL_VERSION_DTLS_1_2	DTLS 1.2, defined by RFC 6347

Since: 2.70