GDtlsClientConnection: GIO Reference Manual

## GDtlsClientConnection GDtlsClientConnection — DTLS client-side connection |

## Functions

GDatagramBased * | g_dtls_client_connection_new ()
void | g_dtls_client_connection_set_server_identity ()
GSocketConnectable * | g_dtls_client_connection_get_server_identity ()
void | g_dtls_client_connection_set_validation_flags ()
GTlsCertificateFlags | g_dtls_client_connection_get_validation_flags ()
GList * | g_dtls_client_connection_get_accepted_cas ()

## Properties

gpointer | accepted-cas | Read
GSocketConnectable * | server-identity | Read / Write / Construct
GTlsCertificateFlags | validation-flags | Read / Write / Construct

## Types and Values

| GDtlsClientConnection
struct | GDtlsClientConnectionInterface

## Object Hierarchy

        GInterface
        ╰── GDtlsClientConnection

## Prerequisites

GDtlsClientConnection requires GDatagramBased, GDtlsConnection and GObject.

## Includes

    #include <gio/gio.h>

## Description

GDtlsClientConnection is the client-side subclass of GDtlsConnection, representing a client-side DTLS connection.

## Functions

### g_dtls_client_connection_new ()

    GDatagramBased *
    g_dtls_client_connection_new (GDatagramBased *base_socket,
                                  GSocketConnectable *server_identity,
                                  GError **error);

Creates a new GDtlsClientConnection wrapping `base_socket` which is assumed to communicate with the server identified by `server_identity` .

#### Parameters

base_socket | the GDatagramBased to wrap |
server_identity | the expected identity of the server. | [nullable]
error | GError for error reporting, or `NULL` to ignore. |

#### Returns

the new GDtlsClientConnection, or `NULL` on error.

[transfer full][type GDtlsClientConnection]

Since: 2.48

### g_dtls_client_connection_set_server_identity ()

    void
    g_dtls_client_connection_set_server_identity
                                   (GDtlsClientConnection *conn,
                                    GSocketConnectable *identity);

Sets `conn` 's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let `conn` know what name to look for in the certificate when performing `G_TLS_CERTIFICATE_BAD_IDENTITY` validation, if enabled.

#### Parameters

conn | the GDtlsClientConnection |
identity | a GSocketConnectable describing the expected server identity |

Since: 2.48

### g_dtls_client_connection_get_server_identity ()

    GSocketConnectable *
    g_dtls_client_connection_get_server_identity
                                   (GDtlsClientConnection *conn);

Gets `conn` 's expected server identity

#### Parameters

conn | the GDtlsClientConnection |

#### Returns

a GSocketConnectable describing the expected server identity, or `NULL` if the expected identity is not known.

[transfer none]

Since: 2.48

### g_dtls_client_connection_set_validation_flags ()

    void
    g_dtls_client_connection_set_validation_flags
                                   (GDtlsClientConnection *conn,
                                    GTlsCertificateFlags flags);

`g_dtls_client_connection_set_validation_flags` has been deprecated since version 2.74 and should not be used in newly-written code.

Do not attempt to ignore validation errors.

Sets `conn` 's validation flags, to override the default set of checks performed when validating a server certificate. By default, `G_TLS_CERTIFICATE_VALIDATE_ALL` is used.

This function does not work as originally designed and is impossible to use correctly. See “validation-flags” for more information.

#### Parameters

conn | the GDtlsClientConnection |
flags | the GTlsCertificateFlags to use |

Since: 2.48

### g_dtls_client_connection_get_validation_flags ()

    GTlsCertificateFlags
    g_dtls_client_connection_get_validation_flags
                                   (GDtlsClientConnection *conn);

`g_dtls_client_connection_get_validation_flags` has been deprecated since version 2.74 and should not be used in newly-written code.

Do not attempt to ignore validation errors.

Gets `conn` 's validation flags

This function does not work as originally designed and is impossible to use correctly. See “validation-flags” for more information.

#### Parameters

conn | the GDtlsClientConnection |

#### Returns

the validation flags

Since: 2.48

### g_dtls_client_connection_get_accepted_cas ()

    GList *
    g_dtls_client_connection_get_accepted_cas
                                   (GDtlsClientConnection *conn);

Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. Otherwise, it will be `NULL`.

Each item in the list is a GByteArray which contains the complete subject DN of the certificate authority.

#### Parameters

conn | the GDtlsClientConnection |

#### Returns

the list of CA DNs. You should unref each element with `g_byte_array_unref()` and then the free the list with `g_list_free()`.

[element-type GByteArray][transfer full]

Since: 2.48

## Types and Values

### GDtlsClientConnection

    typedef struct _GDtlsClientConnection GDtlsClientConnection;

Abstract base class for the backend-specific client connection type.

Since: 2.48

### struct GDtlsClientConnectionInterface

    struct GDtlsClientConnectionInterface {
      GTypeInterface g_iface;
    };

vtable for a GDtlsClientConnection implementation.

#### Members

Since: 2.48

## Property Details

### The `“accepted-cas”` property

      “accepted-cas”             gpointer

A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes.

Each item in the list is a GByteArray which contains the complete subject DN of the certificate authority.

[element-type GLib.ByteArray]

Owner: GDtlsClientConnection

Flags: Read

Since: 2.48

### The `“server-identity”` property

      “server-identity”          GSocketConnectable *

A GSocketConnectable describing the identity of the server that is expected on the other end of the connection.

If the `G_TLS_CERTIFICATE_BAD_IDENTITY` flag is set in “validation-flags”, this object will be used to determine the expected identify of the remote end of the connection; if “server-identity” is not set, or does not match the identity presented by the server, then the `G_TLS_CERTIFICATE_BAD_IDENTITY` validation will fail.

In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts.

Owner: GDtlsClientConnection

Flags: Read / Write / Construct

Since: 2.48

### The `“validation-flags”` property

      “validation-flags”         GTlsCertificateFlags

What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via “accept-certificate”.

GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask `G_TLS_CERTIFICATE_EXPIRED` if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to “accept-certificate”.

`GDtlsClientConnection:validation-flags` has been deprecated since version 2.74 and should not be used in newly-written code.

Do not attempt to ignore validation errors.

Owner: GDtlsClientConnection

Flags: Read / Write / Construct

Default value: G_TLS_CERTIFICATE_UNKNOWN_CA | G_TLS_CERTIFICATE_BAD_IDENTITY | G_TLS_CERTIFICATE_NOT_ACTIVATED | G_TLS_CERTIFICATE_EXPIRED | G_TLS_CERTIFICATE_REVOKED | G_TLS_CERTIFICATE_INSECURE | G_TLS_CERTIFICATE_GENERIC_ERROR

Since: 2.48