Struct DtlsConnection

pub struct DtlsConnection { /* private fields */ }

GDtlsConnection is the base DTLS connection class type, which wraps a DatagramBased and provides DTLS encryption on top of it. Its subclasses, DtlsClientConnection and DtlsServerConnection, implement client-side and server-side DTLS, respectively.

For TLS support, see TlsConnection.

As DTLS is datagram based, GDtlsConnection implements DatagramBased, presenting a datagram-socket-like API for the encrypted connection. This operates over a base datagram connection, which is also a GDatagramBased (base-socket).

To close a DTLS connection, use DtlsConnectionExt::close().

Neither DtlsServerConnection or DtlsClientConnection set the peer address on their base DatagramBased if it is a Socket — it is up to the caller to do that if they wish. If they do not, and SocketExt::close() is called on the base socket, the GDtlsConnection will not raise a G_IO_ERROR_NOT_CONNECTED error on further I/O.

Properties

advertised-protocols

The list of application-layer protocols that the connection advertises that it is willing to speak. See g_dtls_connection_set_advertised_protocols().

Readable | Writeable

base-socket

The #GDatagramBased that the connection wraps. Note that this may be any implementation of #GDatagramBased, not just a #GSocket.

Readable | Writeable | Construct Only

certificate

The connection’s certificate; see g_dtls_connection_set_certificate().

Readable | Writeable

ciphersuite-name

The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name().

Readable

database

The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database().

When using a non-default database, #GDtlsConnection must fall back to using the #GTlsDatabase to perform certificate verification using g_tls_database_verify_chain(), which means certificate verification will not be able to make use of TLS session context. This may be less secure. For example, if you create your own #GTlsDatabase that just wraps the default #GTlsDatabase, you might expect that you have not changed anything, but this is not true because you may have altered the behavior of #GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the documentation of g_tls_database_verify_chain() for more details on specific security checks that may not be performed. Accordingly, setting a non-default database is discouraged except for specialty applications with unusual security requirements.

Readable | Writeable

interaction

A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary.

Readable | Writeable

negotiated-protocol

The application-layer protocol negotiated during the TLS handshake. See g_dtls_connection_get_negotiated_protocol().

Readable

peer-certificate

The connection’s peer’s certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GDtlsConnection::accept-certificate.

(You can watch for a #GObject::notify signal on this property to detect when a handshake has occurred.)

Readable

peer-certificate-errors

The errors noticed while verifying #GDtlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GDtlsClientConnection:validation-flags is not TlsCertificateFlags::VALIDATE_ALL, or if #GDtlsConnection::accept-certificate overrode the default behavior.

GLib guarantees that if certificate verification fails, at least one error will be set, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask TlsCertificateFlags::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.

Readable

protocol-version

The DTLS protocol version in use. See g_dtls_connection_get_protocol_version().

Readable

rehandshake-mode

The rehandshaking mode. See g_dtls_connection_set_rehandshake_mode().

Readable | Writeable | Construct

require-close-notify

Whether or not proper TLS close notification is required. See g_dtls_connection_set_require_close_notify().

Readable | Writeable | Construct

Signals

accept-certificate

Emitted during the TLS handshake after the peer certificate has been received. You can examine @peer_cert’s certification path by calling g_tls_certificate_get_issuer() on it.

For a client-side connection, @peer_cert is the server’s certificate, and the signal will only be emitted if the certificate was not acceptable according to @conn’s #GDtlsClientConnection:validation_flags. If you would like the certificate to be accepted despite @errors, return true from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with TlsError::BadCertificate.

GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in @errors, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to ignore TlsCertificateFlags::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.

For a server-side connection, @peer_cert is the certificate presented by the client, if this was requested via the server’s #GDtlsServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns true.

Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return false from the signal handler on the first attempt, and then after the connection attempt returns a TlsError::BadCertificate, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return true from the signal handler the next time.

If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer.

Implements

DtlsConnectionExt, DatagramBasedExt, DatagramBasedExtManual

GLib type: GObject with reference counted clone semantics.

Implementations

impl DtlsConnection

pub const NONE: Option<&'static DtlsConnection> = None

Trait Implementations

impl Clone for DtlsConnection

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DtlsConnection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasParamSpec for DtlsConnection

type ParamSpec = ParamSpecObject

type SetValue = DtlsConnection

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, DtlsConnection>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for DtlsConnection

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for DtlsConnection

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<OT: ObjectType> PartialEq<OT> for DtlsConnection

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for DtlsConnection

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for DtlsConnection

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for DtlsConnection

impl IsA<DatagramBased> for DtlsConnection

impl IsA<DtlsConnection> for DtlsClientConnection

impl IsA<DtlsConnection> for DtlsServerConnection