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