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