source: appstream-generator/build/girepo/gio/TlsConnection.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 18.7 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module gio.TlsConnection;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import gio.AsyncResultIF;
26private import gio.Cancellable;
27private import gio.IOStream;
28private import gio.TlsCertificate;
29private import gio.TlsDatabase;
30private import gio.TlsInteraction;
31private import glib.ErrorG;
32private import glib.GException;
33private import gobject.ObjectG;
34private import gobject.Signals;
35private import std.algorithm;
36
37
38/**
39 * #GTlsConnection is the base TLS connection class type, which wraps
40 * a #GIOStream and provides TLS encryption on top of it. Its
41 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
42 * implement client-side and server-side TLS, respectively.
43 *
44 * Since: 2.28
45 */
46public class TlsConnection : IOStream
47{
48        /** the main Gtk struct */
49        protected GTlsConnection* gTlsConnection;
50
51        /** Get the main Gtk struct */
52        public GTlsConnection* getTlsConnectionStruct()
53        {
54                return gTlsConnection;
55        }
56
57        /** the main Gtk struct as a void* */
58        protected override void* getStruct()
59        {
60                return cast(void*)gTlsConnection;
61        }
62
63        protected override void setStruct(GObject* obj)
64        {
65                gTlsConnection = cast(GTlsConnection*)obj;
66                super.setStruct(obj);
67        }
68
69        /**
70         * Sets our main struct and passes it to the parent class.
71         */
72        public this (GTlsConnection* gTlsConnection, bool ownedRef = false)
73        {
74                this.gTlsConnection = gTlsConnection;
75                super(cast(GIOStream*)gTlsConnection, ownedRef);
76        }
77
78
79        /** */
80        public static GType getType()
81        {
82                return g_tls_connection_get_type();
83        }
84
85        /**
86         * Used by #GTlsConnection implementations to emit the
87         * #GTlsConnection::accept-certificate signal.
88         *
89         * Params:
90         *     peerCert = the peer's #GTlsCertificate
91         *     errors = the problems with @peer_cert
92         *
93         * Returns: %TRUE if one of the signal handlers has returned
94         *     %TRUE to accept @peer_cert
95         *
96         * Since: 2.28
97         */
98        public bool emitAcceptCertificate(TlsCertificate peerCert, GTlsCertificateFlags errors)
99        {
100                return g_tls_connection_emit_accept_certificate(gTlsConnection, (peerCert is null) ? null : peerCert.getTlsCertificateStruct(), errors) != 0;
101        }
102
103        /**
104         * Gets @conn's certificate, as set by
105         * g_tls_connection_set_certificate().
106         *
107         * Returns: @conn's certificate, or %NULL
108         *
109         * Since: 2.28
110         */
111        public TlsCertificate getCertificate()
112        {
113                auto p = g_tls_connection_get_certificate(gTlsConnection);
114               
115                if(p is null)
116                {
117                        return null;
118                }
119               
120                return ObjectG.getDObject!(TlsCertificate)(cast(GTlsCertificate*) p);
121        }
122
123        /**
124         * Gets the certificate database that @conn uses to verify
125         * peer certificates. See g_tls_connection_set_database().
126         *
127         * Returns: the certificate database that @conn uses or %NULL
128         *
129         * Since: 2.30
130         */
131        public TlsDatabase getDatabase()
132        {
133                auto p = g_tls_connection_get_database(gTlsConnection);
134               
135                if(p is null)
136                {
137                        return null;
138                }
139               
140                return ObjectG.getDObject!(TlsDatabase)(cast(GTlsDatabase*) p);
141        }
142
143        /**
144         * Get the object that will be used to interact with the user. It will be used
145         * for things like prompting the user for passwords. If %NULL is returned, then
146         * no user interaction will occur for this connection.
147         *
148         * Returns: The interaction object.
149         *
150         * Since: 2.30
151         */
152        public TlsInteraction getInteraction()
153        {
154                auto p = g_tls_connection_get_interaction(gTlsConnection);
155               
156                if(p is null)
157                {
158                        return null;
159                }
160               
161                return ObjectG.getDObject!(TlsInteraction)(cast(GTlsInteraction*) p);
162        }
163
164        /**
165         * Gets @conn's peer's certificate after the handshake has completed.
166         * (It is not set during the emission of
167         * #GTlsConnection::accept-certificate.)
168         *
169         * Returns: @conn's peer's certificate, or %NULL
170         *
171         * Since: 2.28
172         */
173        public TlsCertificate getPeerCertificate()
174        {
175                auto p = g_tls_connection_get_peer_certificate(gTlsConnection);
176               
177                if(p is null)
178                {
179                        return null;
180                }
181               
182                return ObjectG.getDObject!(TlsCertificate)(cast(GTlsCertificate*) p);
183        }
184
185        /**
186         * Gets the errors associated with validating @conn's peer's
187         * certificate, after the handshake has completed. (It is not set
188         * during the emission of #GTlsConnection::accept-certificate.)
189         *
190         * Returns: @conn's peer's certificate errors
191         *
192         * Since: 2.28
193         */
194        public GTlsCertificateFlags getPeerCertificateErrors()
195        {
196                return g_tls_connection_get_peer_certificate_errors(gTlsConnection);
197        }
198
199        /**
200         * Gets @conn rehandshaking mode. See
201         * g_tls_connection_set_rehandshake_mode() for details.
202         *
203         * Returns: @conn's rehandshaking mode
204         *
205         * Since: 2.28
206         */
207        public GTlsRehandshakeMode getRehandshakeMode()
208        {
209                return g_tls_connection_get_rehandshake_mode(gTlsConnection);
210        }
211
212        /**
213         * Tests whether or not @conn expects a proper TLS close notification
214         * when the connection is closed. See
215         * g_tls_connection_set_require_close_notify() for details.
216         *
217         * Returns: %TRUE if @conn requires a proper TLS close
218         *     notification.
219         *
220         * Since: 2.28
221         */
222        public bool getRequireCloseNotify()
223        {
224                return g_tls_connection_get_require_close_notify(gTlsConnection) != 0;
225        }
226
227        /**
228         * Gets whether @conn uses the system certificate database to verify
229         * peer certificates. See g_tls_connection_set_use_system_certdb().
230         *
231         * Deprecated: Use g_tls_connection_get_database() instead
232         *
233         * Returns: whether @conn uses the system certificate database
234         */
235        public bool getUseSystemCertdb()
236        {
237                return g_tls_connection_get_use_system_certdb(gTlsConnection) != 0;
238        }
239
240        /**
241         * Attempts a TLS handshake on @conn.
242         *
243         * On the client side, it is never necessary to call this method;
244         * although the connection needs to perform a handshake after
245         * connecting (or after sending a "STARTTLS"-type command) and may
246         * need to rehandshake later if the server requests it,
247         * #GTlsConnection will handle this for you automatically when you try
248         * to send or receive data on the connection. However, you can call
249         * g_tls_connection_handshake() manually if you want to know for sure
250         * whether the initial handshake succeeded or failed (as opposed to
251         * just immediately trying to write to @conn's output stream, in which
252         * case if it fails, it may not be possible to tell if it failed
253         * before or after completing the handshake).
254         *
255         * Likewise, on the server side, although a handshake is necessary at
256         * the beginning of the communication, you do not need to call this
257         * function explicitly unless you want clearer error reporting.
258         * However, you may call g_tls_connection_handshake() later on to
259         * renegotiate parameters (encryption methods, etc) with the client.
260         *
261         * #GTlsConnection::accept_certificate may be emitted during the
262         * handshake.
263         *
264         * Params:
265         *     cancellable = a #GCancellable, or %NULL
266         *
267         * Returns: success or failure
268         *
269         * Since: 2.28
270         *
271         * Throws: GException on failure.
272         */
273        public bool handshake(Cancellable cancellable)
274        {
275                GError* err = null;
276               
277                auto p = g_tls_connection_handshake(gTlsConnection, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0;
278               
279                if (err !is null)
280                {
281                        throw new GException( new ErrorG(err) );
282                }
283               
284                return p;
285        }
286
287        /**
288         * Asynchronously performs a TLS handshake on @conn. See
289         * g_tls_connection_handshake() for more information.
290         *
291         * Params:
292         *     ioPriority = the [I/O priority][io-priority] of the request
293         *     cancellable = a #GCancellable, or %NULL
294         *     callback = callback to call when the handshake is complete
295         *     userData = the data to pass to the callback function
296         *
297         * Since: 2.28
298         */
299        public void handshakeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
300        {
301                g_tls_connection_handshake_async(gTlsConnection, ioPriority, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
302        }
303
304        /**
305         * Finish an asynchronous TLS handshake operation. See
306         * g_tls_connection_handshake() for more information.
307         *
308         * Params:
309         *     result = a #GAsyncResult.
310         *
311         * Returns: %TRUE on success, %FALSE on failure, in which
312         *     case @error will be set.
313         *
314         * Since: 2.28
315         *
316         * Throws: GException on failure.
317         */
318        public bool handshakeFinish(AsyncResultIF result)
319        {
320                GError* err = null;
321               
322                auto p = g_tls_connection_handshake_finish(gTlsConnection, (result is null) ? null : result.getAsyncResultStruct(), &err) != 0;
323               
324                if (err !is null)
325                {
326                        throw new GException( new ErrorG(err) );
327                }
328               
329                return p;
330        }
331
332        /**
333         * This sets the certificate that @conn will present to its peer
334         * during the TLS handshake. For a #GTlsServerConnection, it is
335         * mandatory to set this, and that will normally be done at construct
336         * time.
337         *
338         * For a #GTlsClientConnection, this is optional. If a handshake fails
339         * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
340         * requires a certificate, and if you try connecting again, you should
341         * call this method first. You can call
342         * g_tls_client_connection_get_accepted_cas() on the failed connection
343         * to get a list of Certificate Authorities that the server will
344         * accept certificates from.
345         *
346         * (It is also possible that a server will allow the connection with
347         * or without a certificate; in that case, if you don't provide a
348         * certificate, you can tell that the server requested one by the fact
349         * that g_tls_client_connection_get_accepted_cas() will return
350         * non-%NULL.)
351         *
352         * Params:
353         *     certificate = the certificate to use for @conn
354         *
355         * Since: 2.28
356         */
357        public void setCertificate(TlsCertificate certificate)
358        {
359                g_tls_connection_set_certificate(gTlsConnection, (certificate is null) ? null : certificate.getTlsCertificateStruct());
360        }
361
362        /**
363         * Sets the certificate database that is used to verify peer certificates.
364         * This is set to the default database by default. See
365         * g_tls_backend_get_default_database(). If set to %NULL, then
366         * peer certificate validation will always set the
367         * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
368         * #GTlsConnection::accept-certificate will always be emitted on
369         * client-side connections, unless that bit is not set in
370         * #GTlsClientConnection:validation-flags).
371         *
372         * Params:
373         *     database = a #GTlsDatabase
374         *
375         * Since: 2.30
376         */
377        public void setDatabase(TlsDatabase database)
378        {
379                g_tls_connection_set_database(gTlsConnection, (database is null) ? null : database.getTlsDatabaseStruct());
380        }
381
382        /**
383         * Set the object that will be used to interact with the user. It will be used
384         * for things like prompting the user for passwords.
385         *
386         * The @interaction argument will normally be a derived subclass of
387         * #GTlsInteraction. %NULL can also be provided if no user interaction
388         * should occur for this connection.
389         *
390         * Params:
391         *     interaction = an interaction object, or %NULL
392         *
393         * Since: 2.30
394         */
395        public void setInteraction(TlsInteraction interaction)
396        {
397                g_tls_connection_set_interaction(gTlsConnection, (interaction is null) ? null : interaction.getTlsInteractionStruct());
398        }
399
400        /**
401         * Sets how @conn behaves with respect to rehandshaking requests.
402         *
403         * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
404         * rehandshake after the initial handshake is complete. (For a client,
405         * this means it will refuse rehandshake requests from the server, and
406         * for a server, this means it will close the connection with an error
407         * if the client attempts to rehandshake.)
408         *
409         * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
410         * rehandshake only if the other end of the connection supports the
411         * TLS `renegotiation_info` extension. This is the default behavior,
412         * but means that rehandshaking will not work against older
413         * implementations that do not support that extension.
414         *
415         * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
416         * rehandshaking even without the `renegotiation_info` extension. On
417         * the server side in particular, this is not recommended, since it
418         * leaves the server open to certain attacks. However, this mode is
419         * necessary if you need to allow renegotiation with older client
420         * software.
421         *
422         * Params:
423         *     mode = the rehandshaking mode
424         *
425         * Since: 2.28
426         */
427        public void setRehandshakeMode(GTlsRehandshakeMode mode)
428        {
429                g_tls_connection_set_rehandshake_mode(gTlsConnection, mode);
430        }
431
432        /**
433         * Sets whether or not @conn expects a proper TLS close notification
434         * before the connection is closed. If this is %TRUE (the default),
435         * then @conn will expect to receive a TLS close notification from its
436         * peer before the connection is closed, and will return a
437         * %G_TLS_ERROR_EOF error if the connection is closed without proper
438         * notification (since this may indicate a network error, or
439         * man-in-the-middle attack).
440         *
441         * In some protocols, the application will know whether or not the
442         * connection was closed cleanly based on application-level data
443         * (because the application-level data includes a length field, or is
444         * somehow self-delimiting); in this case, the close notify is
445         * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
446         * in TLS 1.0 it is technically an error, but often done anyway.) You
447         * can use g_tls_connection_set_require_close_notify() to tell @conn
448         * to allow an "unannounced" connection close, in which case the close
449         * will show up as a 0-length read, as in a non-TLS
450         * #GSocketConnection, and it is up to the application to check that
451         * the data has been fully received.
452         *
453         * Note that this only affects the behavior when the peer closes the
454         * connection; when the application calls g_io_stream_close() itself
455         * on @conn, this will send a close notification regardless of the
456         * setting of this property. If you explicitly want to do an unclean
457         * close, you can close @conn's #GTlsConnection:base-io-stream rather
458         * than closing @conn itself.
459         *
460         * Params:
461         *     requireCloseNotify = whether or not to require close notification
462         *
463         * Since: 2.28
464         */
465        public void setRequireCloseNotify(bool requireCloseNotify)
466        {
467                g_tls_connection_set_require_close_notify(gTlsConnection, requireCloseNotify);
468        }
469
470        /**
471         * Sets whether @conn uses the system certificate database to verify
472         * peer certificates. This is %TRUE by default. If set to %FALSE, then
473         * peer certificate validation will always set the
474         * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
475         * #GTlsConnection::accept-certificate will always be emitted on
476         * client-side connections, unless that bit is not set in
477         * #GTlsClientConnection:validation-flags).
478         *
479         * Deprecated: Use g_tls_connection_set_database() instead
480         *
481         * Params:
482         *     useSystemCertdb = whether to use the system certificate database
483         */
484        public void setUseSystemCertdb(bool useSystemCertdb)
485        {
486                g_tls_connection_set_use_system_certdb(gTlsConnection, useSystemCertdb);
487        }
488
489        protected class OnAcceptCertificateDelegateWrapper
490        {
491                static OnAcceptCertificateDelegateWrapper[] listeners;
492                bool delegate(TlsCertificate, GTlsCertificateFlags, TlsConnection) dlg;
493                gulong handlerId;
494               
495                this(bool delegate(TlsCertificate, GTlsCertificateFlags, TlsConnection) dlg)
496                {
497                        this.dlg = dlg;
498                        this.listeners ~= this;
499                }
500               
501                void remove(OnAcceptCertificateDelegateWrapper source)
502                {
503                        foreach(index, wrapper; listeners)
504                        {
505                                if (wrapper.handlerId == source.handlerId)
506                                {
507                                        listeners[index] = null;
508                                        listeners = std.algorithm.remove(listeners, index);
509                                        break;
510                                }
511                        }
512                }
513        }
514
515        /**
516         * Emitted during the TLS handshake after the peer certificate has
517         * been received. You can examine @peer_cert's certification path by
518         * calling g_tls_certificate_get_issuer() on it.
519         *
520         * For a client-side connection, @peer_cert is the server's
521         * certificate, and the signal will only be emitted if the
522         * certificate was not acceptable according to @conn's
523         * #GTlsClientConnection:validation_flags. If you would like the
524         * certificate to be accepted despite @errors, return %TRUE from the
525         * signal handler. Otherwise, if no handler accepts the certificate,
526         * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
527         *
528         * For a server-side connection, @peer_cert is the certificate
529         * presented by the client, if this was requested via the server's
530         * #GTlsServerConnection:authentication_mode. On the server side,
531         * the signal is always emitted when the client presents a
532         * certificate, and the certificate will only be accepted if a
533         * handler returns %TRUE.
534         *
535         * Note that if this signal is emitted as part of asynchronous I/O
536         * in the main thread, then you should not attempt to interact with
537         * the user before returning from the signal handler. If you want to
538         * let the user decide whether or not to accept the certificate, you
539         * would have to return %FALSE from the signal handler on the first
540         * attempt, and then after the connection attempt returns a
541         * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
542         * the user decides to accept the certificate, remember that fact,
543         * create a new connection, and return %TRUE from the signal handler
544         * the next time.
545         *
546         * If you are doing I/O in another thread, you do not
547         * need to worry about this, and can simply block in the signal
548         * handler until the UI thread returns an answer.
549         *
550         * Params:
551         *     peerCert = the peer's #GTlsCertificate
552         *     errors = the problems with @peer_cert.
553         *
554         * Returns: %TRUE to accept @peer_cert (which will also
555         *     immediately end the signal emission). %FALSE to allow the signal
556         *     emission to continue, which will cause the handshake to fail if
557         *     no one else overrides it.
558         *
559         * Since: 2.28
560         */
561        gulong addOnAcceptCertificate(bool delegate(TlsCertificate, GTlsCertificateFlags, TlsConnection) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
562        {
563                auto wrapper = new OnAcceptCertificateDelegateWrapper(dlg);
564                wrapper.handlerId = Signals.connectData(
565                        this,
566                        "accept-certificate",
567                        cast(GCallback)&callBackAcceptCertificate,
568                        cast(void*)wrapper,
569                        cast(GClosureNotify)&callBackAcceptCertificateDestroy,
570                        connectFlags);
571                return wrapper.handlerId;
572        }
573       
574        extern(C) static int callBackAcceptCertificate(GTlsConnection* tlsconnectionStruct, GTlsCertificate* peerCert, GTlsCertificateFlags errors, OnAcceptCertificateDelegateWrapper wrapper)
575        {
576                return wrapper.dlg(ObjectG.getDObject!(TlsCertificate)(peerCert), errors, wrapper.outer);
577        }
578       
579        extern(C) static void callBackAcceptCertificateDestroy(OnAcceptCertificateDelegateWrapper wrapper, GClosure* closure)
580        {
581                wrapper.remove(wrapper);
582        }
583}
Note: See TracBrowser for help on using the repository browser.