1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.DtlsConnectionIF;
26 
27 private import gio.AsyncResultIF;
28 private import gio.Cancellable;
29 private import gio.TlsCertificate;
30 private import gio.TlsDatabase;
31 private import gio.TlsInteraction;
32 private import gio.c.functions;
33 public  import gio.c.types;
34 private import glib.ErrorG;
35 private import glib.GException;
36 private import gobject.ObjectG;
37 private import gobject.Signals;
38 public  import gtkc.giotypes;
39 private import std.algorithm;
40 
41 
42 /**
43  * #GDtlsConnection is the base DTLS connection class type, which wraps
44  * a #GDatagramBased and provides DTLS encryption on top of it. Its
45  * subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
46  * implement client-side and server-side DTLS, respectively.
47  * 
48  * For TLS support, see #GTlsConnection.
49  * 
50  * As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
51  * presenting a datagram-socket-like API for the encrypted connection. This
52  * operates over a base datagram connection, which is also a #GDatagramBased
53  * (#GDtlsConnection:base-socket).
54  * 
55  * To close a DTLS connection, use g_dtls_connection_close().
56  * 
57  * Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
58  * on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
59  * do that if they wish. If they do not, and g_socket_close() is called on the
60  * base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
61  * error on further I/O.
62  *
63  * Since: 2.48
64  */
65 public interface DtlsConnectionIF{
66 	/** Get the main Gtk struct */
67 	public GDtlsConnection* getDtlsConnectionStruct(bool transferOwnership = false);
68 
69 	/** the main Gtk struct as a void* */
70 	protected void* getStruct();
71 
72 
73 	/** */
74 	public static GType getType()
75 	{
76 		return g_dtls_connection_get_type();
77 	}
78 
79 	/**
80 	 * Close the DTLS connection. This is equivalent to calling
81 	 * g_dtls_connection_shutdown() to shut down both sides of the connection.
82 	 *
83 	 * Closing a #GDtlsConnection waits for all buffered but untransmitted data to
84 	 * be sent before it completes. It then sends a `close_notify` DTLS alert to the
85 	 * peer and may wait for a `close_notify` to be received from the peer. It does
86 	 * not close the underlying #GDtlsConnection:base-socket; that must be closed
87 	 * separately.
88 	 *
89 	 * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED.
90 	 * Closing a #GDtlsConnection multiple times will not return an error.
91 	 *
92 	 * #GDtlsConnections will be automatically closed when the last reference is
93 	 * dropped, but you might want to call this function to make sure resources are
94 	 * released as early as possible.
95 	 *
96 	 * If @cancellable is cancelled, the #GDtlsConnection may be left
97 	 * partially-closed and any pending untransmitted data may be lost. Call
98 	 * g_dtls_connection_close() again to complete closing the #GDtlsConnection.
99 	 *
100 	 * Params:
101 	 *     cancellable = a #GCancellable, or %NULL
102 	 *
103 	 * Returns: %TRUE on success, %FALSE otherwise
104 	 *
105 	 * Since: 2.48
106 	 *
107 	 * Throws: GException on failure.
108 	 */
109 	public bool close(Cancellable cancellable);
110 
111 	/**
112 	 * Asynchronously close the DTLS connection. See g_dtls_connection_close() for
113 	 * more information.
114 	 *
115 	 * Params:
116 	 *     ioPriority = the [I/O priority][io-priority] of the request
117 	 *     cancellable = a #GCancellable, or %NULL
118 	 *     callback = callback to call when the close operation is complete
119 	 *     userData = the data to pass to the callback function
120 	 *
121 	 * Since: 2.48
122 	 */
123 	public void closeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
124 
125 	/**
126 	 * Finish an asynchronous TLS close operation. See g_dtls_connection_close()
127 	 * for more information.
128 	 *
129 	 * Params:
130 	 *     result = a #GAsyncResult
131 	 *
132 	 * Returns: %TRUE on success, %FALSE on failure, in which
133 	 *     case @error will be set
134 	 *
135 	 * Since: 2.48
136 	 *
137 	 * Throws: GException on failure.
138 	 */
139 	public bool closeFinish(AsyncResultIF result);
140 
141 	/**
142 	 * Used by #GDtlsConnection implementations to emit the
143 	 * #GDtlsConnection::accept-certificate signal.
144 	 *
145 	 * Params:
146 	 *     peerCert = the peer's #GTlsCertificate
147 	 *     errors = the problems with @peer_cert
148 	 *
149 	 * Returns: %TRUE if one of the signal handlers has returned
150 	 *     %TRUE to accept @peer_cert
151 	 *
152 	 * Since: 2.48
153 	 */
154 	public bool emitAcceptCertificate(TlsCertificate peerCert, GTlsCertificateFlags errors);
155 
156 	/**
157 	 * Gets @conn's certificate, as set by
158 	 * g_dtls_connection_set_certificate().
159 	 *
160 	 * Returns: @conn's certificate, or %NULL
161 	 *
162 	 * Since: 2.48
163 	 */
164 	public TlsCertificate getCertificate();
165 
166 	/**
167 	 * Gets the certificate database that @conn uses to verify
168 	 * peer certificates. See g_dtls_connection_set_database().
169 	 *
170 	 * Returns: the certificate database that @conn uses or %NULL
171 	 *
172 	 * Since: 2.48
173 	 */
174 	public TlsDatabase getDatabase();
175 
176 	/**
177 	 * Get the object that will be used to interact with the user. It will be used
178 	 * for things like prompting the user for passwords. If %NULL is returned, then
179 	 * no user interaction will occur for this connection.
180 	 *
181 	 * Returns: The interaction object.
182 	 *
183 	 * Since: 2.48
184 	 */
185 	public TlsInteraction getInteraction();
186 
187 	/**
188 	 * Gets @conn's peer's certificate after the handshake has completed.
189 	 * (It is not set during the emission of
190 	 * #GDtlsConnection::accept-certificate.)
191 	 *
192 	 * Returns: @conn's peer's certificate, or %NULL
193 	 *
194 	 * Since: 2.48
195 	 */
196 	public TlsCertificate getPeerCertificate();
197 
198 	/**
199 	 * Gets the errors associated with validating @conn's peer's
200 	 * certificate, after the handshake has completed. (It is not set
201 	 * during the emission of #GDtlsConnection::accept-certificate.)
202 	 *
203 	 * Returns: @conn's peer's certificate errors
204 	 *
205 	 * Since: 2.48
206 	 */
207 	public GTlsCertificateFlags getPeerCertificateErrors();
208 
209 	/**
210 	 * Gets @conn rehandshaking mode. See
211 	 * g_dtls_connection_set_rehandshake_mode() for details.
212 	 *
213 	 * Returns: @conn's rehandshaking mode
214 	 *
215 	 * Since: 2.48
216 	 */
217 	public GTlsRehandshakeMode getRehandshakeMode();
218 
219 	/**
220 	 * Tests whether or not @conn expects a proper TLS close notification
221 	 * when the connection is closed. See
222 	 * g_dtls_connection_set_require_close_notify() for details.
223 	 *
224 	 * Returns: %TRUE if @conn requires a proper TLS close notification.
225 	 *
226 	 * Since: 2.48
227 	 */
228 	public bool getRequireCloseNotify();
229 
230 	/**
231 	 * Attempts a TLS handshake on @conn.
232 	 *
233 	 * On the client side, it is never necessary to call this method;
234 	 * although the connection needs to perform a handshake after
235 	 * connecting (or after sending a "STARTTLS"-type command) and may
236 	 * need to rehandshake later if the server requests it,
237 	 * #GDtlsConnection will handle this for you automatically when you try
238 	 * to send or receive data on the connection. However, you can call
239 	 * g_dtls_connection_handshake() manually if you want to know for sure
240 	 * whether the initial handshake succeeded or failed (as opposed to
241 	 * just immediately trying to write to @conn, in which
242 	 * case if it fails, it may not be possible to tell if it failed
243 	 * before or after completing the handshake).
244 	 *
245 	 * Likewise, on the server side, although a handshake is necessary at
246 	 * the beginning of the communication, you do not need to call this
247 	 * function explicitly unless you want clearer error reporting.
248 	 * However, you may call g_dtls_connection_handshake() later on to
249 	 * renegotiate parameters (encryption methods, etc) with the client.
250 	 *
251 	 * #GDtlsConnection::accept_certificate may be emitted during the
252 	 * handshake.
253 	 *
254 	 * Params:
255 	 *     cancellable = a #GCancellable, or %NULL
256 	 *
257 	 * Returns: success or failure
258 	 *
259 	 * Since: 2.48
260 	 *
261 	 * Throws: GException on failure.
262 	 */
263 	public bool handshake(Cancellable cancellable);
264 
265 	/**
266 	 * Asynchronously performs a TLS handshake on @conn. See
267 	 * g_dtls_connection_handshake() for more information.
268 	 *
269 	 * Params:
270 	 *     ioPriority = the [I/O priority][io-priority] of the request
271 	 *     cancellable = a #GCancellable, or %NULL
272 	 *     callback = callback to call when the handshake is complete
273 	 *     userData = the data to pass to the callback function
274 	 *
275 	 * Since: 2.48
276 	 */
277 	public void handshakeAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
278 
279 	/**
280 	 * Finish an asynchronous TLS handshake operation. See
281 	 * g_dtls_connection_handshake() for more information.
282 	 *
283 	 * Params:
284 	 *     result = a #GAsyncResult.
285 	 *
286 	 * Returns: %TRUE on success, %FALSE on failure, in which
287 	 *     case @error will be set.
288 	 *
289 	 * Since: 2.48
290 	 *
291 	 * Throws: GException on failure.
292 	 */
293 	public bool handshakeFinish(AsyncResultIF result);
294 
295 	/**
296 	 * This sets the certificate that @conn will present to its peer
297 	 * during the TLS handshake. For a #GDtlsServerConnection, it is
298 	 * mandatory to set this, and that will normally be done at construct
299 	 * time.
300 	 *
301 	 * For a #GDtlsClientConnection, this is optional. If a handshake fails
302 	 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
303 	 * requires a certificate, and if you try connecting again, you should
304 	 * call this method first. You can call
305 	 * g_dtls_client_connection_get_accepted_cas() on the failed connection
306 	 * to get a list of Certificate Authorities that the server will
307 	 * accept certificates from.
308 	 *
309 	 * (It is also possible that a server will allow the connection with
310 	 * or without a certificate; in that case, if you don't provide a
311 	 * certificate, you can tell that the server requested one by the fact
312 	 * that g_dtls_client_connection_get_accepted_cas() will return
313 	 * non-%NULL.)
314 	 *
315 	 * Params:
316 	 *     certificate = the certificate to use for @conn
317 	 *
318 	 * Since: 2.48
319 	 */
320 	public void setCertificate(TlsCertificate certificate);
321 
322 	/**
323 	 * Sets the certificate database that is used to verify peer certificates.
324 	 * This is set to the default database by default. See
325 	 * g_tls_backend_get_default_database(). If set to %NULL, then
326 	 * peer certificate validation will always set the
327 	 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
328 	 * #GDtlsConnection::accept-certificate will always be emitted on
329 	 * client-side connections, unless that bit is not set in
330 	 * #GDtlsClientConnection:validation-flags).
331 	 *
332 	 * Params:
333 	 *     database = a #GTlsDatabase
334 	 *
335 	 * Since: 2.48
336 	 */
337 	public void setDatabase(TlsDatabase database);
338 
339 	/**
340 	 * Set the object that will be used to interact with the user. It will be used
341 	 * for things like prompting the user for passwords.
342 	 *
343 	 * The @interaction argument will normally be a derived subclass of
344 	 * #GTlsInteraction. %NULL can also be provided if no user interaction
345 	 * should occur for this connection.
346 	 *
347 	 * Params:
348 	 *     interaction = an interaction object, or %NULL
349 	 *
350 	 * Since: 2.48
351 	 */
352 	public void setInteraction(TlsInteraction interaction);
353 
354 	/**
355 	 * Sets how @conn behaves with respect to rehandshaking requests.
356 	 *
357 	 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
358 	 * rehandshake after the initial handshake is complete. (For a client,
359 	 * this means it will refuse rehandshake requests from the server, and
360 	 * for a server, this means it will close the connection with an error
361 	 * if the client attempts to rehandshake.)
362 	 *
363 	 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
364 	 * rehandshake only if the other end of the connection supports the
365 	 * TLS `renegotiation_info` extension. This is the default behavior,
366 	 * but means that rehandshaking will not work against older
367 	 * implementations that do not support that extension.
368 	 *
369 	 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
370 	 * rehandshaking even without the `renegotiation_info` extension. On
371 	 * the server side in particular, this is not recommended, since it
372 	 * leaves the server open to certain attacks. However, this mode is
373 	 * necessary if you need to allow renegotiation with older client
374 	 * software.
375 	 *
376 	 * Params:
377 	 *     mode = the rehandshaking mode
378 	 *
379 	 * Since: 2.48
380 	 */
381 	public void setRehandshakeMode(GTlsRehandshakeMode mode);
382 
383 	/**
384 	 * Sets whether or not @conn expects a proper TLS close notification
385 	 * before the connection is closed. If this is %TRUE (the default),
386 	 * then @conn will expect to receive a TLS close notification from its
387 	 * peer before the connection is closed, and will return a
388 	 * %G_TLS_ERROR_EOF error if the connection is closed without proper
389 	 * notification (since this may indicate a network error, or
390 	 * man-in-the-middle attack).
391 	 *
392 	 * In some protocols, the application will know whether or not the
393 	 * connection was closed cleanly based on application-level data
394 	 * (because the application-level data includes a length field, or is
395 	 * somehow self-delimiting); in this case, the close notify is
396 	 * redundant and may be omitted. You
397 	 * can use g_dtls_connection_set_require_close_notify() to tell @conn
398 	 * to allow an "unannounced" connection close, in which case the close
399 	 * will show up as a 0-length read, as in a non-TLS
400 	 * #GDatagramBased, and it is up to the application to check that
401 	 * the data has been fully received.
402 	 *
403 	 * Note that this only affects the behavior when the peer closes the
404 	 * connection; when the application calls g_dtls_connection_close_async() on
405 	 * @conn itself, this will send a close notification regardless of the
406 	 * setting of this property. If you explicitly want to do an unclean
407 	 * close, you can close @conn's #GDtlsConnection:base-socket rather
408 	 * than closing @conn itself.
409 	 *
410 	 * Params:
411 	 *     requireCloseNotify = whether or not to require close notification
412 	 *
413 	 * Since: 2.48
414 	 */
415 	public void setRequireCloseNotify(bool requireCloseNotify);
416 
417 	/**
418 	 * Shut down part or all of a DTLS connection.
419 	 *
420 	 * If @shutdown_read is %TRUE then the receiving side of the connection is shut
421 	 * down, and further reading is disallowed. Subsequent calls to
422 	 * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
423 	 *
424 	 * If @shutdown_write is %TRUE then the sending side of the connection is shut
425 	 * down, and further writing is disallowed. Subsequent calls to
426 	 * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
427 	 *
428 	 * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
429 	 * is equivalent to calling g_dtls_connection_close().
430 	 *
431 	 * If @cancellable is cancelled, the #GDtlsConnection may be left
432 	 * partially-closed and any pending untransmitted data may be lost. Call
433 	 * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
434 	 *
435 	 * Params:
436 	 *     shutdownRead = %TRUE to stop reception of incoming datagrams
437 	 *     shutdownWrite = %TRUE to stop sending outgoing datagrams
438 	 *     cancellable = a #GCancellable, or %NULL
439 	 *
440 	 * Returns: %TRUE on success, %FALSE otherwise
441 	 *
442 	 * Since: 2.48
443 	 *
444 	 * Throws: GException on failure.
445 	 */
446 	public bool shutdown(bool shutdownRead, bool shutdownWrite, Cancellable cancellable);
447 
448 	/**
449 	 * Asynchronously shut down part or all of the DTLS connection. See
450 	 * g_dtls_connection_shutdown() for more information.
451 	 *
452 	 * Params:
453 	 *     shutdownRead = %TRUE to stop reception of incoming datagrams
454 	 *     shutdownWrite = %TRUE to stop sending outgoing datagrams
455 	 *     ioPriority = the [I/O priority][io-priority] of the request
456 	 *     cancellable = a #GCancellable, or %NULL
457 	 *     callback = callback to call when the shutdown operation is complete
458 	 *     userData = the data to pass to the callback function
459 	 *
460 	 * Since: 2.48
461 	 */
462 	public void shutdownAsync(bool shutdownRead, bool shutdownWrite, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
463 
464 	/**
465 	 * Finish an asynchronous TLS shutdown operation. See
466 	 * g_dtls_connection_shutdown() for more information.
467 	 *
468 	 * Params:
469 	 *     result = a #GAsyncResult
470 	 *
471 	 * Returns: %TRUE on success, %FALSE on failure, in which
472 	 *     case @error will be set
473 	 *
474 	 * Since: 2.48
475 	 *
476 	 * Throws: GException on failure.
477 	 */
478 	public bool shutdownFinish(AsyncResultIF result);
479 
480 	/**
481 	 * Emitted during the TLS handshake after the peer certificate has
482 	 * been received. You can examine @peer_cert's certification path by
483 	 * calling g_tls_certificate_get_issuer() on it.
484 	 *
485 	 * For a client-side connection, @peer_cert is the server's
486 	 * certificate, and the signal will only be emitted if the
487 	 * certificate was not acceptable according to @conn's
488 	 * #GDtlsClientConnection:validation_flags. If you would like the
489 	 * certificate to be accepted despite @errors, return %TRUE from the
490 	 * signal handler. Otherwise, if no handler accepts the certificate,
491 	 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
492 	 *
493 	 * For a server-side connection, @peer_cert is the certificate
494 	 * presented by the client, if this was requested via the server's
495 	 * #GDtlsServerConnection:authentication_mode. On the server side,
496 	 * the signal is always emitted when the client presents a
497 	 * certificate, and the certificate will only be accepted if a
498 	 * handler returns %TRUE.
499 	 *
500 	 * Note that if this signal is emitted as part of asynchronous I/O
501 	 * in the main thread, then you should not attempt to interact with
502 	 * the user before returning from the signal handler. If you want to
503 	 * let the user decide whether or not to accept the certificate, you
504 	 * would have to return %FALSE from the signal handler on the first
505 	 * attempt, and then after the connection attempt returns a
506 	 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
507 	 * the user decides to accept the certificate, remember that fact,
508 	 * create a new connection, and return %TRUE from the signal handler
509 	 * the next time.
510 	 *
511 	 * If you are doing I/O in another thread, you do not
512 	 * need to worry about this, and can simply block in the signal
513 	 * handler until the UI thread returns an answer.
514 	 *
515 	 * Params:
516 	 *     peerCert = the peer's #GTlsCertificate
517 	 *     errors = the problems with @peer_cert.
518 	 *
519 	 * Returns: %TRUE to accept @peer_cert (which will also
520 	 *     immediately end the signal emission). %FALSE to allow the signal
521 	 *     emission to continue, which will cause the handshake to fail if
522 	 *     no one else overrides it.
523 	 *
524 	 * Since: 2.48
525 	 */
526 	gulong addOnAcceptCertificate(bool delegate(TlsCertificate, GTlsCertificateFlags, DtlsConnectionIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
527 }