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

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