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