gio/auto/

tls_client_connection.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT
#![allow(deprecated)]

use crate::{ffi, IOStream, SocketConnectable, TlsCertificateFlags, TlsConnection};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// `GTlsClientConnection` is the client-side subclass of
    /// [`TlsConnection`][crate::TlsConnection], representing a client-side TLS connection.
    ///
    /// ## Properties
    ///
    ///
    /// #### `accepted-cas`
    ///  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.
    ///
    /// Readable
    ///
    ///
    /// #### `server-identity`
    ///  A #GSocketConnectable describing the identity of the server that
    /// is expected on the other end of the connection.
    ///
    /// If the [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] flag is set in
    /// #GTlsClientConnection:validation-flags, this object will be used
    /// to determine the expected identify of the remote end of the
    /// connection; if #GTlsClientConnection:server-identity is not set,
    /// or does not match the identity presented by the server, then the
    /// [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::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.
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `use-ssl3`
    ///  SSL 3.0 is no longer supported. See
    /// g_tls_client_connection_set_use_ssl3() for details.
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `validation-flags`
    ///  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 #GTlsConnection::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
    /// [`TlsCertificateFlags::EXPIRED`][crate::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. 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 #GTlsConnection::accept-certificate.
    ///
    /// Readable | Writeable | Construct
    /// <details><summary><h4>TlsConnection</h4></summary>
    ///
    ///
    /// #### `advertised-protocols`
    ///  The list of application-layer protocols that the connection
    /// advertises that it is willing to speak. See
    /// g_tls_connection_set_advertised_protocols().
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `base-io-stream`
    ///  The #GIOStream that the connection wraps. The connection holds a reference
    /// to this stream, and may run operations on the stream from other threads
    /// throughout its lifetime. Consequently, after the #GIOStream has been
    /// constructed, application code may only run its own operations on this
    /// stream when no #GIOStream operations are running.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `certificate`
    ///  The connection's certificate; see
    /// g_tls_connection_set_certificate().
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `ciphersuite-name`
    ///  The name of the TLS ciphersuite in use. See g_tls_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, #GTlsConnection 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
    /// #GTlsConnection 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_tls_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 #GTlsConnection::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
    /// #GTlsConnection:peer-certificate. Normally this should be 0, but
    /// it may not be if #GTlsClientConnection:validation-flags is not
    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL], or if
    /// #GTlsConnection::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`][crate::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 TLS protocol version in use. See g_tls_connection_get_protocol_version().
    ///
    /// Readable
    ///
    ///
    /// #### `rehandshake-mode`
    ///  The rehandshaking mode. See
    /// g_tls_connection_set_rehandshake_mode().
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `require-close-notify`
    ///  Whether or not proper TLS close notification is required.
    /// See g_tls_connection_set_require_close_notify().
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `use-system-certdb`
    ///  Whether or not the system certificate database will be used to
    /// verify peer certificates. See
    /// g_tls_connection_set_use_system_certdb().
    ///
    /// Readable | Writeable | Construct
    /// </details>
    /// <details><summary><h4>IOStream</h4></summary>
    ///
    ///
    /// #### `closed`
    ///  Whether the stream is closed.
    ///
    /// Readable
    ///
    ///
    /// #### `input-stream`
    ///  The [`InputStream`][crate::InputStream] to read from.
    ///
    /// Readable
    ///
    ///
    /// #### `output-stream`
    ///  The [`OutputStream`][crate::OutputStream] to write to.
    ///
    /// Readable
    /// </details>
    ///
    /// # Implements
    ///
    /// [`TlsClientConnectionExt`][trait@crate::prelude::TlsClientConnectionExt], [`TlsConnectionExt`][trait@crate::prelude::TlsConnectionExt], [`IOStreamExt`][trait@crate::prelude::IOStreamExt], [`trait@glib::ObjectExt`], [`TlsConnectionExtManual`][trait@crate::prelude::TlsConnectionExtManual], [`IOStreamExtManual`][trait@crate::prelude::IOStreamExtManual]
    #[doc(alias = "GTlsClientConnection")]
    pub struct TlsClientConnection(Interface<ffi::GTlsClientConnection, ffi::GTlsClientConnectionInterface>) @requires TlsConnection, IOStream;

    match fn {
        type_ => || ffi::g_tls_client_connection_get_type(),
    }
}

impl TlsClientConnection {
    pub const NONE: Option<&'static TlsClientConnection> = None;

    /// Creates a new #GTlsClientConnection wrapping @base_io_stream (which
    /// must have pollable input and output streams) which is assumed to
    /// communicate with the server identified by @server_identity.
    ///
    /// See the documentation for #GTlsConnection:base-io-stream for restrictions
    /// on when application code can run operations on the @base_io_stream after
    /// this function has returned.
    /// ## `base_io_stream`
    /// the #GIOStream to wrap
    /// ## `server_identity`
    /// the expected identity of the server
    ///
    /// # Returns
    ///
    /// the new
    /// #GTlsClientConnection, or [`None`] on error
    #[doc(alias = "g_tls_client_connection_new")]
    pub fn new(
        base_io_stream: &impl IsA<IOStream>,
        server_identity: Option<&impl IsA<SocketConnectable>>,
    ) -> Result<TlsClientConnection, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_tls_client_connection_new(
                base_io_stream.as_ref().to_glib_none().0,
                server_identity.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

/// Trait containing all [`struct@TlsClientConnection`] methods.
///
/// # Implementors
///
/// [`TlsClientConnection`][struct@crate::TlsClientConnection]
pub trait TlsClientConnectionExt: IsA<TlsClientConnection> + 'static {
    /// Possibly copies session state from one connection to another, for use
    /// in TLS session resumption. This is not normally needed, but may be
    /// used when the same session needs to be used between different
    /// endpoints, as is required by some protocols, such as FTP over TLS.
    /// @source should have already completed a handshake and, since TLS 1.3,
    /// it should have been used to read data at least once. @self should not
    /// have completed a handshake.
    ///
    /// It is not possible to know whether a call to this function will
    /// actually do anything. Because session resumption is normally used
    /// only for performance benefit, the TLS backend might not implement
    /// this function. Even if implemented, it may not actually succeed in
    /// allowing @self to resume @source's TLS session, because the server
    /// may not have sent a session resumption token to @source, or it may
    /// refuse to accept the token from @self. There is no way to know
    /// whether a call to this function is actually successful.
    ///
    /// Using this function is not required to benefit from session
    /// resumption. If the TLS backend supports session resumption, the
    /// session will be resumed automatically if it is possible to do so
    /// without weakening the privacy guarantees normally provided by TLS,
    /// without need to call this function. For example, with TLS 1.3,
    /// a session ticket will be automatically copied from any
    /// #GTlsClientConnection that has previously received session tickets
    /// from the server, provided a ticket is available that has not
    /// previously been used for session resumption, since session ticket
    /// reuse would be a privacy weakness. Using this function causes the
    /// ticket to be copied without regard for privacy considerations.
    /// ## `source`
    /// a #GTlsClientConnection
    #[doc(alias = "g_tls_client_connection_copy_session_state")]
    fn copy_session_state(&self, source: &impl IsA<TlsClientConnection>) {
        unsafe {
            ffi::g_tls_client_connection_copy_session_state(
                self.as_ref().to_glib_none().0,
                source.as_ref().to_glib_none().0,
            );
        }
    }

    /// 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 [`None`].
    ///
    /// Each item in the list is a #GByteArray which contains the complete
    /// subject DN of the certificate authority.
    ///
    /// # 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().
    #[doc(alias = "g_tls_client_connection_get_accepted_cas")]
    #[doc(alias = "get_accepted_cas")]
    #[doc(alias = "accepted-cas")]
    fn accepted_cas(&self) -> Vec<glib::ByteArray> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_tls_client_connection_get_accepted_cas(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets @self's expected server identity
    ///
    /// # Returns
    ///
    /// a #GSocketConnectable describing the
    /// expected server identity, or [`None`] if the expected identity is not
    /// known.
    #[doc(alias = "g_tls_client_connection_get_server_identity")]
    #[doc(alias = "get_server_identity")]
    #[doc(alias = "server-identity")]
    fn server_identity(&self) -> Option<SocketConnectable> {
        unsafe {
            from_glib_none(ffi::g_tls_client_connection_get_server_identity(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets @self's validation flags
    ///
    /// This function does not work as originally designed and is impossible
    /// to use correctly. See #GTlsClientConnection:validation-flags for more
    /// information.
    ///
    /// # Deprecated since 2.72
    ///
    /// Do not attempt to ignore validation errors.
    ///
    /// # Returns
    ///
    /// the validation flags
    #[cfg_attr(feature = "v2_72", deprecated = "Since 2.72")]
    #[allow(deprecated)]
    #[doc(alias = "g_tls_client_connection_get_validation_flags")]
    #[doc(alias = "get_validation_flags")]
    #[doc(alias = "validation-flags")]
    fn validation_flags(&self) -> TlsCertificateFlags {
        unsafe {
            from_glib(ffi::g_tls_client_connection_get_validation_flags(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Sets @self's expected server identity, which is used both to tell
    /// servers on virtual hosts which certificate to present, and also
    /// to let @self know what name to look for in the certificate when
    /// performing [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] validation, if enabled.
    /// ## `identity`
    /// a #GSocketConnectable describing the expected server identity
    #[doc(alias = "g_tls_client_connection_set_server_identity")]
    #[doc(alias = "server-identity")]
    fn set_server_identity(&self, identity: &impl IsA<SocketConnectable>) {
        unsafe {
            ffi::g_tls_client_connection_set_server_identity(
                self.as_ref().to_glib_none().0,
                identity.as_ref().to_glib_none().0,
            );
        }
    }

    /// Sets @self's validation flags, to override the default set of
    /// checks performed when validating a server certificate. By default,
    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL] is used.
    ///
    /// This function does not work as originally designed and is impossible
    /// to use correctly. See #GTlsClientConnection:validation-flags for more
    /// information.
    ///
    /// # Deprecated since 2.72
    ///
    /// Do not attempt to ignore validation errors.
    /// ## `flags`
    /// the #GTlsCertificateFlags to use
    #[cfg_attr(feature = "v2_72", deprecated = "Since 2.72")]
    #[allow(deprecated)]
    #[doc(alias = "g_tls_client_connection_set_validation_flags")]
    #[doc(alias = "validation-flags")]
    fn set_validation_flags(&self, flags: TlsCertificateFlags) {
        unsafe {
            ffi::g_tls_client_connection_set_validation_flags(
                self.as_ref().to_glib_none().0,
                flags.into_glib(),
            );
        }
    }

    #[doc(alias = "accepted-cas")]
    fn connect_accepted_cas_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_accepted_cas_trampoline<
            P: IsA<TlsClientConnection>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GTlsClientConnection,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(TlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::accepted-cas".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_accepted_cas_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "server-identity")]
    fn connect_server_identity_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_server_identity_trampoline<
            P: IsA<TlsClientConnection>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GTlsClientConnection,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(TlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::server-identity".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_server_identity_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg_attr(feature = "v2_72", deprecated = "Since 2.72")]
    #[doc(alias = "validation-flags")]
    fn connect_validation_flags_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_validation_flags_trampoline<
            P: IsA<TlsClientConnection>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GTlsClientConnection,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(TlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::validation-flags".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_validation_flags_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<TlsClientConnection>> TlsClientConnectionExt for O {}