TLS Overview

TLS Overview — TLS (aka SSL) support for GSocketConnection

Synopsis

#include <gio/gio.h>

#define             G_TLS_ERROR
enum                GTlsError;

enum                GTlsAuthenticationMode;
enum                GTlsCertificateFlags;

Object Hierarchy

  GEnum
   +----GTlsAuthenticationMode

  GFlags
   +----GTlsCertificateFlags

Description

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

In the simplest case, for a client 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.

Details

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

typedef enum {
  G_TLS_ERROR_UNAVAILABLE,
  G_TLS_ERROR_MISC,
  G_TLS_ERROR_BAD_CERTIFICATE,
  G_TLS_ERROR_NOT_TLS,
  G_TLS_ERROR_HANDSHAKE,
  G_TLS_ERROR_CERTIFICATE_REQUIRED,
  G_TLS_ERROR_EOF
} GTlsError;

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

`G_TLS_ERROR_UNAVAILABLE`	No TLS provider is available
`G_TLS_ERROR_MISC`	Miscellaneous TLS error
`G_TLS_ERROR_BAD_CERTIFICATE`	A certificate could not be parsed
`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()`.

Since 2.28

enum GTlsAuthenticationMode

typedef enum {
  G_TLS_AUTHENTICATION_NONE,
  G_TLS_AUTHENTICATION_REQUESTED,
  G_TLS_AUTHENTICATION_REQUIRED
} GTlsAuthenticationMode;

The client authentication mode for a GTlsServerConnection.

`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

typedef enum {
  G_TLS_CERTIFICATE_UNKNOWN_CA    = (1 << 0),
  G_TLS_CERTIFICATE_BAD_IDENTITY  = (1 << 1),
  G_TLS_CERTIFICATE_NOT_ACTIVATED = (1 << 2),
  G_TLS_CERTIFICATE_EXPIRED       = (1 << 3),
  G_TLS_CERTIFICATE_REVOKED       = (1 << 4),
  G_TLS_CERTIFICATE_INSECURE      = (1 << 5),
  G_TLS_CERTIFICATE_GENERIC_ERROR = (1 << 6),

  G_TLS_CERTIFICATE_VALIDATE_ALL  = 0x007f
} 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").

`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 GTlsContext'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

			GIO Reference Manual
Top \| Description \| Object Hierarchy