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

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.

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

Gets `conn` 's validation flags

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

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