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 {}