gio/auto/
tls_client_connection.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4#![allow(deprecated)]
5
6use crate::{ffi, IOStream, SocketConnectable, TlsCertificateFlags, TlsConnection};
7use glib::{
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// `GTlsClientConnection` is the client-side subclass of
16    /// [`TlsConnection`][crate::TlsConnection], representing a client-side TLS connection.
17    ///
18    /// ## Properties
19    ///
20    ///
21    /// #### `accepted-cas`
22    ///  A list of the distinguished names of the Certificate Authorities
23    /// that the server will accept client certificates signed by. If the
24    /// server requests a client certificate during the handshake, then
25    /// this property will be set after the handshake completes.
26    ///
27    /// Each item in the list is a #GByteArray which contains the complete
28    /// subject DN of the certificate authority.
29    ///
30    /// Readable
31    ///
32    ///
33    /// #### `server-identity`
34    ///  A #GSocketConnectable describing the identity of the server that
35    /// is expected on the other end of the connection.
36    ///
37    /// If the [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] flag is set in
38    /// #GTlsClientConnection:validation-flags, this object will be used
39    /// to determine the expected identify of the remote end of the
40    /// connection; if #GTlsClientConnection:server-identity is not set,
41    /// or does not match the identity presented by the server, then the
42    /// [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] validation will fail.
43    ///
44    /// In addition to its use in verifying the server certificate,
45    /// this is also used to give a hint to the server about what
46    /// certificate we expect, which is useful for servers that serve
47    /// virtual hosts.
48    ///
49    /// Readable | Writeable | Construct
50    ///
51    ///
52    /// #### `use-ssl3`
53    ///  SSL 3.0 is no longer supported. See
54    /// g_tls_client_connection_set_use_ssl3() for details.
55    ///
56    /// Readable | Writeable | Construct
57    ///
58    ///
59    /// #### `validation-flags`
60    ///  What steps to perform when validating a certificate received from
61    /// a server. Server certificates that fail to validate in any of the
62    /// ways indicated here will be rejected unless the application
63    /// overrides the default via #GTlsConnection::accept-certificate.
64    ///
65    /// GLib guarantees that if certificate verification fails, at least one
66    /// flag will be set, but it does not guarantee that all possible flags
67    /// will be set. Accordingly, you may not safely decide to ignore any
68    /// particular type of error. For example, it would be incorrect to mask
69    /// [`TlsCertificateFlags::EXPIRED`][crate::TlsCertificateFlags::EXPIRED] if you want to allow expired certificates,
70    /// because this could potentially be the only error flag set even if
71    /// other problems exist with the certificate. Therefore, there is no
72    /// safe way to use this property. This is not a horrible problem,
73    /// though, because you should not be attempting to ignore validation
74    /// errors anyway. If you really must ignore TLS certificate errors,
75    /// connect to #GTlsConnection::accept-certificate.
76    ///
77    /// Readable | Writeable | Construct
78    /// <details><summary><h4>TlsConnection</h4></summary>
79    ///
80    ///
81    /// #### `advertised-protocols`
82    ///  The list of application-layer protocols that the connection
83    /// advertises that it is willing to speak. See
84    /// g_tls_connection_set_advertised_protocols().
85    ///
86    /// Readable | Writeable
87    ///
88    ///
89    /// #### `base-io-stream`
90    ///  The #GIOStream that the connection wraps. The connection holds a reference
91    /// to this stream, and may run operations on the stream from other threads
92    /// throughout its lifetime. Consequently, after the #GIOStream has been
93    /// constructed, application code may only run its own operations on this
94    /// stream when no #GIOStream operations are running.
95    ///
96    /// Readable | Writeable | Construct Only
97    ///
98    ///
99    /// #### `certificate`
100    ///  The connection's certificate; see
101    /// g_tls_connection_set_certificate().
102    ///
103    /// Readable | Writeable
104    ///
105    ///
106    /// #### `ciphersuite-name`
107    ///  The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name().
108    ///
109    /// Readable
110    ///
111    ///
112    /// #### `database`
113    ///  The certificate database to use when verifying this TLS connection.
114    /// If no certificate database is set, then the default database will be
115    /// used. See g_tls_backend_get_default_database().
116    ///
117    /// When using a non-default database, #GTlsConnection must fall back to using
118    /// the #GTlsDatabase to perform certificate verification using
119    /// g_tls_database_verify_chain(), which means certificate verification will
120    /// not be able to make use of TLS session context. This may be less secure.
121    /// For example, if you create your own #GTlsDatabase that just wraps the
122    /// default #GTlsDatabase, you might expect that you have not changed anything,
123    /// but this is not true because you may have altered the behavior of
124    /// #GTlsConnection by causing it to use g_tls_database_verify_chain(). See the
125    /// documentation of g_tls_database_verify_chain() for more details on specific
126    /// security checks that may not be performed. Accordingly, setting a
127    /// non-default database is discouraged except for specialty applications with
128    /// unusual security requirements.
129    ///
130    /// Readable | Writeable
131    ///
132    ///
133    /// #### `interaction`
134    ///  A #GTlsInteraction object to be used when the connection or certificate
135    /// database need to interact with the user. This will be used to prompt the
136    /// user for passwords where necessary.
137    ///
138    /// Readable | Writeable
139    ///
140    ///
141    /// #### `negotiated-protocol`
142    ///  The application-layer protocol negotiated during the TLS
143    /// handshake. See g_tls_connection_get_negotiated_protocol().
144    ///
145    /// Readable
146    ///
147    ///
148    /// #### `peer-certificate`
149    ///  The connection's peer's certificate, after the TLS handshake has
150    /// completed or failed. Note in particular that this is not yet set
151    /// during the emission of #GTlsConnection::accept-certificate.
152    ///
153    /// (You can watch for a #GObject::notify signal on this property to
154    /// detect when a handshake has occurred.)
155    ///
156    /// Readable
157    ///
158    ///
159    /// #### `peer-certificate-errors`
160    ///  The errors noticed while verifying
161    /// #GTlsConnection:peer-certificate. Normally this should be 0, but
162    /// it may not be if #GTlsClientConnection:validation-flags is not
163    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL], or if
164    /// #GTlsConnection::accept-certificate overrode the default
165    /// behavior.
166    ///
167    /// GLib guarantees that if certificate verification fails, at least
168    /// one error will be set, but it does not guarantee that all possible
169    /// errors will be set. Accordingly, you may not safely decide to
170    /// ignore any particular type of error. For example, it would be
171    /// incorrect to mask [`TlsCertificateFlags::EXPIRED`][crate::TlsCertificateFlags::EXPIRED] if you want to allow
172    /// expired certificates, because this could potentially be the only
173    /// error flag set even if other problems exist with the certificate.
174    ///
175    /// Readable
176    ///
177    ///
178    /// #### `protocol-version`
179    ///  The TLS protocol version in use. See g_tls_connection_get_protocol_version().
180    ///
181    /// Readable
182    ///
183    ///
184    /// #### `rehandshake-mode`
185    ///  The rehandshaking mode. See
186    /// g_tls_connection_set_rehandshake_mode().
187    ///
188    /// Readable | Writeable | Construct
189    ///
190    ///
191    /// #### `require-close-notify`
192    ///  Whether or not proper TLS close notification is required.
193    /// See g_tls_connection_set_require_close_notify().
194    ///
195    /// Readable | Writeable | Construct
196    ///
197    ///
198    /// #### `use-system-certdb`
199    ///  Whether or not the system certificate database will be used to
200    /// verify peer certificates. See
201    /// g_tls_connection_set_use_system_certdb().
202    ///
203    /// Readable | Writeable | Construct
204    /// </details>
205    /// <details><summary><h4>IOStream</h4></summary>
206    ///
207    ///
208    /// #### `closed`
209    ///  Whether the stream is closed.
210    ///
211    /// Readable
212    ///
213    ///
214    /// #### `input-stream`
215    ///  The [`InputStream`][crate::InputStream] to read from.
216    ///
217    /// Readable
218    ///
219    ///
220    /// #### `output-stream`
221    ///  The [`OutputStream`][crate::OutputStream] to write to.
222    ///
223    /// Readable
224    /// </details>
225    ///
226    /// # Implements
227    ///
228    /// [`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]
229    #[doc(alias = "GTlsClientConnection")]
230    pub struct TlsClientConnection(Interface<ffi::GTlsClientConnection, ffi::GTlsClientConnectionInterface>) @requires TlsConnection, IOStream;
231
232    match fn {
233        type_ => || ffi::g_tls_client_connection_get_type(),
234    }
235}
236
237impl TlsClientConnection {
238    pub const NONE: Option<&'static TlsClientConnection> = None;
239
240    /// Creates a new #GTlsClientConnection wrapping @base_io_stream (which
241    /// must have pollable input and output streams) which is assumed to
242    /// communicate with the server identified by @server_identity.
243    ///
244    /// See the documentation for #GTlsConnection:base-io-stream for restrictions
245    /// on when application code can run operations on the @base_io_stream after
246    /// this function has returned.
247    /// ## `base_io_stream`
248    /// the #GIOStream to wrap
249    /// ## `server_identity`
250    /// the expected identity of the server
251    ///
252    /// # Returns
253    ///
254    /// the new
255    /// #GTlsClientConnection, or [`None`] on error
256    #[doc(alias = "g_tls_client_connection_new")]
257    pub fn new(
258        base_io_stream: &impl IsA<IOStream>,
259        server_identity: Option<&impl IsA<SocketConnectable>>,
260    ) -> Result<TlsClientConnection, glib::Error> {
261        unsafe {
262            let mut error = std::ptr::null_mut();
263            let ret = ffi::g_tls_client_connection_new(
264                base_io_stream.as_ref().to_glib_none().0,
265                server_identity.map(|p| p.as_ref()).to_glib_none().0,
266                &mut error,
267            );
268            if error.is_null() {
269                Ok(from_glib_full(ret))
270            } else {
271                Err(from_glib_full(error))
272            }
273        }
274    }
275}
276
277mod sealed {
278    pub trait Sealed {}
279    impl<T: super::IsA<super::TlsClientConnection>> Sealed for T {}
280}
281
282/// Trait containing all [`struct@TlsClientConnection`] methods.
283///
284/// # Implementors
285///
286/// [`TlsClientConnection`][struct@crate::TlsClientConnection]
287pub trait TlsClientConnectionExt: IsA<TlsClientConnection> + sealed::Sealed + 'static {
288    /// Possibly copies session state from one connection to another, for use
289    /// in TLS session resumption. This is not normally needed, but may be
290    /// used when the same session needs to be used between different
291    /// endpoints, as is required by some protocols, such as FTP over TLS.
292    /// @source should have already completed a handshake and, since TLS 1.3,
293    /// it should have been used to read data at least once. @self should not
294    /// have completed a handshake.
295    ///
296    /// It is not possible to know whether a call to this function will
297    /// actually do anything. Because session resumption is normally used
298    /// only for performance benefit, the TLS backend might not implement
299    /// this function. Even if implemented, it may not actually succeed in
300    /// allowing @self to resume @source's TLS session, because the server
301    /// may not have sent a session resumption token to @source, or it may
302    /// refuse to accept the token from @self. There is no way to know
303    /// whether a call to this function is actually successful.
304    ///
305    /// Using this function is not required to benefit from session
306    /// resumption. If the TLS backend supports session resumption, the
307    /// session will be resumed automatically if it is possible to do so
308    /// without weakening the privacy guarantees normally provided by TLS,
309    /// without need to call this function. For example, with TLS 1.3,
310    /// a session ticket will be automatically copied from any
311    /// #GTlsClientConnection that has previously received session tickets
312    /// from the server, provided a ticket is available that has not
313    /// previously been used for session resumption, since session ticket
314    /// reuse would be a privacy weakness. Using this function causes the
315    /// ticket to be copied without regard for privacy considerations.
316    /// ## `source`
317    /// a #GTlsClientConnection
318    #[doc(alias = "g_tls_client_connection_copy_session_state")]
319    fn copy_session_state(&self, source: &impl IsA<TlsClientConnection>) {
320        unsafe {
321            ffi::g_tls_client_connection_copy_session_state(
322                self.as_ref().to_glib_none().0,
323                source.as_ref().to_glib_none().0,
324            );
325        }
326    }
327
328    /// Gets the list of distinguished names of the Certificate Authorities
329    /// that the server will accept certificates from. This will be set
330    /// during the TLS handshake if the server requests a certificate.
331    /// Otherwise, it will be [`None`].
332    ///
333    /// Each item in the list is a #GByteArray which contains the complete
334    /// subject DN of the certificate authority.
335    ///
336    /// # Returns
337    ///
338    /// the list of
339    /// CA DNs. You should unref each element with g_byte_array_unref() and then
340    /// the free the list with g_list_free().
341    #[doc(alias = "g_tls_client_connection_get_accepted_cas")]
342    #[doc(alias = "get_accepted_cas")]
343    #[doc(alias = "accepted-cas")]
344    fn accepted_cas(&self) -> Vec<glib::ByteArray> {
345        unsafe {
346            FromGlibPtrContainer::from_glib_full(ffi::g_tls_client_connection_get_accepted_cas(
347                self.as_ref().to_glib_none().0,
348            ))
349        }
350    }
351
352    /// Gets @self's expected server identity
353    ///
354    /// # Returns
355    ///
356    /// a #GSocketConnectable describing the
357    /// expected server identity, or [`None`] if the expected identity is not
358    /// known.
359    #[doc(alias = "g_tls_client_connection_get_server_identity")]
360    #[doc(alias = "get_server_identity")]
361    #[doc(alias = "server-identity")]
362    fn server_identity(&self) -> Option<SocketConnectable> {
363        unsafe {
364            from_glib_none(ffi::g_tls_client_connection_get_server_identity(
365                self.as_ref().to_glib_none().0,
366            ))
367        }
368    }
369
370    /// Gets @self's validation flags
371    ///
372    /// This function does not work as originally designed and is impossible
373    /// to use correctly. See #GTlsClientConnection:validation-flags for more
374    /// information.
375    ///
376    /// # Deprecated since 2.72
377    ///
378    /// Do not attempt to ignore validation errors.
379    ///
380    /// # Returns
381    ///
382    /// the validation flags
383    #[cfg_attr(feature = "v2_72", deprecated = "Since 2.72")]
384    #[allow(deprecated)]
385    #[doc(alias = "g_tls_client_connection_get_validation_flags")]
386    #[doc(alias = "get_validation_flags")]
387    #[doc(alias = "validation-flags")]
388    fn validation_flags(&self) -> TlsCertificateFlags {
389        unsafe {
390            from_glib(ffi::g_tls_client_connection_get_validation_flags(
391                self.as_ref().to_glib_none().0,
392            ))
393        }
394    }
395
396    /// Sets @self's expected server identity, which is used both to tell
397    /// servers on virtual hosts which certificate to present, and also
398    /// to let @self know what name to look for in the certificate when
399    /// performing [`TlsCertificateFlags::BAD_IDENTITY`][crate::TlsCertificateFlags::BAD_IDENTITY] validation, if enabled.
400    /// ## `identity`
401    /// a #GSocketConnectable describing the expected server identity
402    #[doc(alias = "g_tls_client_connection_set_server_identity")]
403    #[doc(alias = "server-identity")]
404    fn set_server_identity(&self, identity: &impl IsA<SocketConnectable>) {
405        unsafe {
406            ffi::g_tls_client_connection_set_server_identity(
407                self.as_ref().to_glib_none().0,
408                identity.as_ref().to_glib_none().0,
409            );
410        }
411    }
412
413    /// Sets @self's validation flags, to override the default set of
414    /// checks performed when validating a server certificate. By default,
415    /// [`TlsCertificateFlags::VALIDATE_ALL`][crate::TlsCertificateFlags::VALIDATE_ALL] is used.
416    ///
417    /// This function does not work as originally designed and is impossible
418    /// to use correctly. See #GTlsClientConnection:validation-flags for more
419    /// information.
420    ///
421    /// # Deprecated since 2.72
422    ///
423    /// Do not attempt to ignore validation errors.
424    /// ## `flags`
425    /// the #GTlsCertificateFlags to use
426    #[cfg_attr(feature = "v2_72", deprecated = "Since 2.72")]
427    #[allow(deprecated)]
428    #[doc(alias = "g_tls_client_connection_set_validation_flags")]
429    #[doc(alias = "validation-flags")]
430    fn set_validation_flags(&self, flags: TlsCertificateFlags) {
431        unsafe {
432            ffi::g_tls_client_connection_set_validation_flags(
433                self.as_ref().to_glib_none().0,
434                flags.into_glib(),
435            );
436        }
437    }
438
439    #[doc(alias = "accepted-cas")]
440    fn connect_accepted_cas_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
441        unsafe extern "C" fn notify_accepted_cas_trampoline<
442            P: IsA<TlsClientConnection>,
443            F: Fn(&P) + 'static,
444        >(
445            this: *mut ffi::GTlsClientConnection,
446            _param_spec: glib::ffi::gpointer,
447            f: glib::ffi::gpointer,
448        ) {
449            let f: &F = &*(f as *const F);
450            f(TlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
451        }
452        unsafe {
453            let f: Box_<F> = Box_::new(f);
454            connect_raw(
455                self.as_ptr() as *mut _,
456                b"notify::accepted-cas\0".as_ptr() as *const _,
457                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
458                    notify_accepted_cas_trampoline::<Self, F> as *const (),
459                )),
460                Box_::into_raw(f),
461            )
462        }
463    }
464
465    #[doc(alias = "server-identity")]
466    fn connect_server_identity_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
467        unsafe extern "C" fn notify_server_identity_trampoline<
468            P: IsA<TlsClientConnection>,
469            F: Fn(&P) + 'static,
470        >(
471            this: *mut ffi::GTlsClientConnection,
472            _param_spec: glib::ffi::gpointer,
473            f: glib::ffi::gpointer,
474        ) {
475            let f: &F = &*(f as *const F);
476            f(TlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
477        }
478        unsafe {
479            let f: Box_<F> = Box_::new(f);
480            connect_raw(
481                self.as_ptr() as *mut _,
482                b"notify::server-identity\0".as_ptr() as *const _,
483                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
484                    notify_server_identity_trampoline::<Self, F> as *const (),
485                )),
486                Box_::into_raw(f),
487            )
488        }
489    }
490
491    #[cfg_attr(feature = "v2_72", deprecated = "Since 2.72")]
492    #[doc(alias = "validation-flags")]
493    fn connect_validation_flags_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
494        unsafe extern "C" fn notify_validation_flags_trampoline<
495            P: IsA<TlsClientConnection>,
496            F: Fn(&P) + 'static,
497        >(
498            this: *mut ffi::GTlsClientConnection,
499            _param_spec: glib::ffi::gpointer,
500            f: glib::ffi::gpointer,
501        ) {
502            let f: &F = &*(f as *const F);
503            f(TlsClientConnection::from_glib_borrow(this).unsafe_cast_ref())
504        }
505        unsafe {
506            let f: Box_<F> = Box_::new(f);
507            connect_raw(
508                self.as_ptr() as *mut _,
509                b"notify::validation-flags\0".as_ptr() as *const _,
510                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
511                    notify_validation_flags_trampoline::<Self, F> as *const (),
512                )),
513                Box_::into_raw(f),
514            )
515        }
516    }
517}
518
519impl<O: IsA<TlsClientConnection>> TlsClientConnectionExt for O {}