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