GIO Reference Manual: TLS Overview

## TLS Overview TLS Overview — TLS (aka SSL) support for GSocketConnection |

## Functions

#define | G_TLS_ERROR

## Types and Values

enum | GTlsError
enum | GTlsAuthenticationMode
enum | GTlsCertificateFlags

## Object Hierarchy

        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.

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.

## Functions

### 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.

## Types and Values

### 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 | 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

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