Overview
Comment: | Renamed BIO read/write functions to input/output to avoid confusion with API names. Added PKI and Certificates section to docs. Added/updated comments, formatting updates, etc. |
---|---|
Downloads: | Tarball | ZIP archive | SQL archive |
Timelines: | family | ancestors | descendants | both | trunk | main |
Files: | files | file ages | folders |
SHA3-256: |
3848af25d21c11a06e633874b5d45963 |
User & Date: | bohagan on 2024-12-29 04:18:00 |
Other Links: | branch diff | manifest | tags |
Context
2024-12-29
| ||
04:36 | Added IO buffer checks to TlsChannelHandlerTimer mask function. Reordered TlsNotifyProc to check conditions prior to timer deletion. Pass buffer length in MessageCallback. check-in: 6252a3a1f5 user: bohagan tags: trunk, main | |
04:18 | Renamed BIO read/write functions to input/output to avoid confusion with API names. Added PKI and Certificates section to docs. Added/updated comments, formatting updates, etc. check-in: 3848af25d2 user: bohagan tags: trunk, main | |
2024-12-24
| ||
04:30 | On Windows, set default value for -castore option to Windows cert store check-in: cfd2090203 user: bohagan tags: trunk, main | |
Changes
Modified doc/tls.html
from [7814ef6b7d]
to [ea1db2c293].
︙ | ︙ | |||
108 109 110 111 112 113 114 | <ul class="doctools_toc"> <li class="doctools_section"><a href="#toc">Table Of Contents</a></li> <li class="doctools_section"><a href="#synopsis">Synopsis</a></li> <li class="doctools_section"><a href="#section1">Description</a></li> <li class="doctools_section"><a href="#section2">Commands</a></li> <li class="doctools_section"><a href="#section3">Certificate Validation</a> <ul> | | | > | | | | 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 | <ul class="doctools_toc"> <li class="doctools_section"><a href="#toc">Table Of Contents</a></li> <li class="doctools_section"><a href="#synopsis">Synopsis</a></li> <li class="doctools_section"><a href="#section1">Description</a></li> <li class="doctools_section"><a href="#section2">Commands</a></li> <li class="doctools_section"><a href="#section3">Certificate Validation</a> <ul> <li class="doctools_subsection"><a href="#subsection1">PKI and Certificates</a></li> <li class="doctools_subsection"><a href="#subsection2">Summary of command line options</a></li> <li class="doctools_subsection"><a href="#subsection3">When are command line options needed?</a></li> </ul> </li> <li class="doctools_section"><a href="#section4">Callback Options</a> <ul> <li class="doctools_subsection"><a href="#subsection4">Values for Command Callback</a></li> <li class="doctools_subsection"><a href="#subsection5">Values for Password Callback</a></li> <li class="doctools_subsection"><a href="#subsection6">Values for Validate Command Callback</a></li> </ul> </li> <li class="doctools_section"><a href="#section5">Debug</a></li> <li class="doctools_section"><a href="#section6">Debug Examples</a></li> <li class="doctools_section"><a href="#section7">HTTP Package Examples</a></li> <li class="doctools_section"><a href="#section8">Special Considerations</a></li> <li class="doctools_section"><a href="#see-also">See Also</a></li> |
︙ | ︙ | |||
200 201 202 203 204 205 206 | <b class="const">quic</b>.</p></dd> <dt><b class="option">-cadir</b> <i class="arg">directory</i></dt> <dd><p>Specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific and can be set at compile time. The default location can be overridden by the <b class="variable">SSL_CERT_DIR</b> environment variable. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd> <dt><b class="option">-cafile</b> <i class="arg">filename</i></dt> | | | | | | | | | | 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 | <b class="const">quic</b>.</p></dd> <dt><b class="option">-cadir</b> <i class="arg">directory</i></dt> <dd><p>Specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific and can be set at compile time. The default location can be overridden by the <b class="variable">SSL_CERT_DIR</b> environment variable. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd> <dt><b class="option">-cafile</b> <i class="arg">filename</i></dt> <dd><p>Specifies the file with the Certificate Authority (CA) certificates to use in <b class="const">PEM</b> file format. The default is "<b class="file">cert.pem</b>", in the OpenSSL directory. The default file can be overridden by the <b class="variable">SSL_CERT_FILE</b> environment variable. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd> <dt><b class="option">-castore</b> <i class="arg">URI</i></dt> <dd><p>Specifies the Uniform Resource Identifier (URI) for the Certificate Authority (CA) store, which may be a single container or a catalog of containers. Starting with OpenSSL 3.2 on MS Windows, set to "<b class="const">org.openssl.winstore://</b>" to use the built-in MS Windows Certificate Store. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd> <dt><b class="option">-certfile</b> <i class="arg">filename</i></dt> <dd><p>Specifies the name of the file with the certificate to use in PEM format as the local (client or server) certificate. It also contains the public key.</p></dd> <dt><b class="option">-cert</b> <i class="arg">string</i></dt> <dd><p>Specifies the certificate to use as a DER encoded string (X.509 DER).</p></dd> <dt><b class="option">-cipher</b> <i class="arg">string</i></dt> <dd><p>Specifies the list of ciphers to use for TLS 1.2 and earlier connections. String is a colon "<b class="const">:</b>" separated list of ciphers. Ciphers can be combined using the "<b class="const">+</b>" character. |
︙ | ︙ | |||
238 239 240 241 242 243 244 | <dt><b class="option">-command</b> <i class="arg">callback</i></dt> <dd><p>Specifies the callback command to be invoked at several points during the handshake to pass errors, tracing information, and protocol messages. See <span class="sectref"><a href="#section4">Callback Options</a></span> for more info.</p></dd> <dt><b class="option">-dhparams</b> <i class="arg">filename</i></dt> <dd><p>Specifies the Diffie-Hellman (DH) parameters file.</p></dd> <dt><b class="option">-keyfile</b> <i class="arg">filename</i></dt> | | | > | | | | > | | | 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 | <dt><b class="option">-command</b> <i class="arg">callback</i></dt> <dd><p>Specifies the callback command to be invoked at several points during the handshake to pass errors, tracing information, and protocol messages. See <span class="sectref"><a href="#section4">Callback Options</a></span> for more info.</p></dd> <dt><b class="option">-dhparams</b> <i class="arg">filename</i></dt> <dd><p>Specifies the Diffie-Hellman (DH) parameters file.</p></dd> <dt><b class="option">-keyfile</b> <i class="arg">filename</i></dt> <dd><p>Specifies the private key file. The default is to use the file specified by the <i class="arg">-certfile</i> option.</p></dd> <dt><b class="option">-key</b> <i class="arg">string</i></dt> <dd><p>Specifies the private key to use as a DER encoded string (PKCS#1 DER).</p></dd> <dt><b class="option">-model</b> <i class="arg">channel</i></dt> <dd><p>Force this channel to share the same <i class="term">SSL_CTX</i> structure as the specified <i class="arg">channel</i>, and therefore share config, callbacks, etc.</p></dd> <dt><b class="option">-password</b> <i class="arg">callback</i></dt> <dd><p>Specifies the callback command to invoke when OpenSSL needs to obtain a password. This is typically used to unlock the private key of a certificate. The callback should return a password string. See <span class="sectref"><a href="#section4">Callback Options</a></span> for more info.</p></dd> <dt><b class="option">-post_handshake</b> <i class="arg">bool</i></dt> <dd><p>Allow post-handshake session ticket updates.</p></dd> <dt><b class="option">-request</b> <i class="arg">bool</i></dt> <dd><p>Request a certificate from the peer during the SSL handshake. This is needed to do Certificate Validation. Starting in TclTLS 1.8, the default is <b class="const">true</b>. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd> <dt><b class="option">-require</b> <i class="arg">bool</i></dt> <dd><p>Require a valid certificate from the peer during the SSL handshake. If this is set to true, then <b class="option">-request</b> must also be set to true and a either <b class="option">-cadir</b>, <b class="option">-cafile</b>, <b class="option">-castore</b>, or a platform default must be provided in order to validate against. The default in TclTLS 1.8 and earlier versions is <b class="const">false</b> since not all platforms have certificates to validate against in a form compatible with OpenSSL. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd> <dt><b class="option">-security_level</b> <i class="arg">integer</i></dt> <dd><p>Specifies the security level (value from 0 to 5). The security level affects the allowed cipher suite encryption algorithms, supported ECC curves, supported signature algorithms, DH parameter sizes, certificate key sizes and signature algorithms. The default is 1 prior to OpenSSL 3.2 and 2 thereafter. Level 3 and higher disable support for session tickets and |
︙ | ︙ | |||
493 494 495 496 497 498 499 | <b class="const">ssl2</b>, <b class="const">ssl3</b>, <b class="const">tls1</b>, <b class="const">tls1.1</b>, <b class="const">tls1.2</b>, and <b class="const">tls1.3</b>. Exact list depends on OpenSSL version and compile time flags.</p></dd> <dt><a name="11"><b class="cmd">tls::version</b></a></dt> <dd><p>Returns the OpenSSL version string.</p></dd> </dl> </div> <div id="section3" class="doctools_section"><h2><a name="section3">Certificate Validation</a></h2> | | > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | > | | | > | | | | | | < > | > | < | | | | | | | > | > | | | | | | > | | | | 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 | <b class="const">ssl2</b>, <b class="const">ssl3</b>, <b class="const">tls1</b>, <b class="const">tls1.1</b>, <b class="const">tls1.2</b>, and <b class="const">tls1.3</b>. Exact list depends on OpenSSL version and compile time flags.</p></dd> <dt><a name="11"><b class="cmd">tls::version</b></a></dt> <dd><p>Returns the OpenSSL version string.</p></dd> </dl> </div> <div id="section3" class="doctools_section"><h2><a name="section3">Certificate Validation</a></h2> <div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">PKI and Certificates</a></h3> <p>Using the Public Key Infrastructure (PKI), each user creates a private key that only they know about and a public key they can exchange with others for use in encrypting and decrypting data. The process is the sender encrypts their data using their private key and the receiver's public key. The data is then sent to the receiver. In a similar manner, the receiver uses their private key and the sender's public key to decrypt the data. This provides data integrity, to ensure the data can't be viewed or altered during transport. See the <b class="option">-key</b> and <b class="option">-keyfile</b> options for how to specify the private key. Also see the <b class="option">-password</b> option for how to provide the password.</p> <p>In order to provide authentication, i.e. ensuring someone is who they say they are, the public key and user identification info is stored in a X.509 certificate and that certificate is authenticated (i.e. signed) by a Certificate Authority (CA). Users can then exchange these certificates during the TLS initialization process and check them against the root CA certificates to ensure they are valid. This is handled by OpenSSL via the <b class="option">-request</b> and <b class="option">-require</b> options. See the <b class="option">-cadir</b>, <b class="option">-cadir</b>, and <b class="option">-castore</b> options for how tp specify where to find the CA certificates. Optionally, in a future release, they can also be checked against the Certificate Revocation List (CRL) of revoked certificates. Certificates can also be self-signed, but they are by default not trusted unless you add them to your certificate store.</p> <p>Typically when visiting web sites, only the client needs to check the server's certificate to ensure it is valid. The server doesn't need to check the client certificate unless you need to authenticate with them to login, etc. See the <b class="option">-cert</b> and <b class="option">-certfile</b> options if you need to provide a certificate.</p> </div> <div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Summary of command line options</a></h3> <p>The following options are used for peer certificate validation:</p> <dl class="doctools_options"> <dt><b class="option">-cadir</b> <i class="arg">directory</i></dt> <dd><p>Specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific, but is usually "<b class="file">/etc/ssl/certs</b>" on Linux/Unix systems. The default location can be overridden by the <b class="variable">SSL_CERT_DIR</b> environment variable.</p></dd> <dt><b class="option">-cafile</b> <i class="arg">filename</i></dt> <dd><p>Specifies the file with the Certificate Authority (CA) certificates to use in <b class="const">PEM</b> file format. The default is "<b class="file">cert.pem</b>", in the OpenSSL directory. On Linux/Unix systems, this is usually "<b class="file">/etc/ssl/ca-bundle.pem</b>". The default file can be overridden by the <b class="variable">SSL_CERT_FILE</b> environment variable.</p></dd> <dt><b class="option">-castore</b> <i class="arg">URI</i></dt> <dd><p>Specifies the Uniform Resource Identifier (URI) for the Certificate Authority (CA) store, which may be a single container or a catalog of containers. Starting with OpenSSL 3.2 on MS Windows, set to "<b class="const">org.openssl.winstore://</b>" to use the built-in MS Windows Certificate Store. This store only supports root certificate stores. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd> <dt><b class="option">-request</b> <i class="arg">bool</i></dt> <dd><p>Request a certificate from the peer during the SSL handshake. This is needed to do Certificate Validation. Starting in TclTLS 1.8, the default is <b class="const">true</b>. In addition, the client can manually inspect and accept or reject each certificate using the <i class="arg">-validatecommand</i> option.</p></dd> <dt><b class="option">-require</b> <i class="arg">bool</i></dt> <dd><p>Require a valid certificate from the peer during the SSL handshake. If this is set to true, then <b class="option">-request</b> must also be set to true and a either <b class="option">-cadir</b>, <b class="option">-cafile</b>, <b class="option">-castore</b>, or a platform default must be provided in order to validate against. The default in TclTLS 1.8 and earlier versions is <b class="const">false</b> since not all platforms have certificates to validate against in a form compatible with OpenSSL.</p></dd> </dl> </div> <div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">When are command line options needed?</a></h3> <p>In TclTLS 1.8 and earlier versions, certificate validation is <em>NOT</em> enabled by default. This limitation is due to the lack of a common cross platform database of Certificate Authority (CA) provided certificates to validate against. Many Linux systems natively support OpenSSL and thus have these certificates installed as part of the OS, but MacOS and MS Windows do not. In order to use the <b class="option">-require</b> option, one of the following must be true:</p> <ul class="doctools_itemized"> <li><p>On Linux and Unix systems with OpenSSL already installed or if the CA certificates are available in PEM format, and if they are stored in the standard locations, or if the <b class="variable">SSL_CERT_DIR</b> or <b class="variable">SSL_CERT_FILE</b> environment variables are set, then <b class="option">-cadir</b>, <b class="option">-cadir</b>, and <b class="option">-castore</b> aren't needed.</p></li> <li><p>If OpenSSL is not installed in the default location, or when using Mac OS or MS Windows and OpenSSL is installed, the <b class="variable">SSL_CERT_DIR</b> and/or <b class="variable">SSL_CERT_FILE</b> environment variables or the one of the <b class="option">-cadir</b>, <b class="option">-cadir</b>, or <b class="option">-castore</b> options must be defined.</p></li> <li><p>On MS Windows, starting in OpenSSL 3.2, it is now possible to access the built-in Windows Certificate Store from OpenSSL. This can utilized by setting the <b class="option">-castore</b> option to "<b class="const">org.openssl.winstore://</b>".</p></li> <li><p>If OpenSSL is not installed or the CA certificates are not available in PEM format, the CA certificates must be downloaded and installed with the user software. The CURL team makes them available at <a href="https://curl.se/docs/caextract.html">CA certificates extracted from Mozilla</a> in the "<b class="file">cacert.pem</b>" file. You must then either set the <b class="variable">SSL_CERT_DIR</b> and/or <b class="variable">SSL_CERT_FILE</b> environment variables or the <b class="option">-cadir</b> or <b class="option">-cafile</b> options to the CA cert file's install location. It is your responsibility to keep this file up to date.</p></li> </ul> </div> </div> <div id="section4" class="doctools_section"><h2><a name="section4">Callback Options</a></h2> <p>As previously described, each channel can be given their own callbacks to handle intermediate processing by the OpenSSL library, using the <b class="option">-command</b>, <b class="option">-password</b>, and <b class="option">-validate_command</b> options passed to either of <b class="cmd">tls::socket</b> or <b class="cmd">tls::import</b>. Unlike previous versions of TclTLS, only if the callback generates an error, will the <b class="syscmd">bgerror</b> command be invoked with the error information.</p> <div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Values for Command Callback</a></h3> <p>The callback for the <b class="option">-command</b> option is invoked at several points during the OpenSSL handshake and during routine operations. See below for the possible arguments passed to the callback script. Values returned from the callback are ignored.</p> <dl class="doctools_options"> <dt><b class="option">error</b> <i class="arg">channelId message</i></dt> <dd><p>This form of callback is invoked whenever an error occurs during the initial |
︙ | ︙ | |||
627 628 629 630 631 632 633 | <dt><i class="arg">lifetime</i></dt> <dd><p>Lifetime is the ticket lifetime in seconds.</p></dd> </dl></dd> <dt><b class="option">verify</b> <i class="arg">channelId depth cert status error</i></dt> <dd><p>This callback was moved to <b class="option">-validatecommand</b> in TclTLS 1.8.</p></dd> </dl> </div> | | | | 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 | <dt><i class="arg">lifetime</i></dt> <dd><p>Lifetime is the ticket lifetime in seconds.</p></dd> </dl></dd> <dt><b class="option">verify</b> <i class="arg">channelId depth cert status error</i></dt> <dd><p>This callback was moved to <b class="option">-validatecommand</b> in TclTLS 1.8.</p></dd> </dl> </div> <div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Values for Password Callback</a></h3> <p>The callback for the <b class="option">-password</b> option is invoked by TclTLS whenever OpenSSL needs to obtain a password. See below for the possible arguments passed to the callback script. The user provided password is expected to be returned by the callback.</p> <dl class="doctools_options"> <dt><b class="option">password</b> <i class="arg">rwflag size</i></dt> <dd><p>Invoked when loading or storing an encrypted PEM certificate. The arguments are:</p> <dl class="doctools_definitions"> <dt><i class="arg">rwflag</i></dt> <dd><p>The read/write flag is 0 for reading/decryption or 1 for writing/encryption. The latter can be used to determine when to prompt the user to confirm. This argument is new for TclTLS 1.8.</p></dd> <dt><i class="arg">size</i></dt> <dd><p>The size is the maximum length of the password in bytes. This argument is new for TclTLS 1.8.</p></dd> </dl></dd> </dl> </div> <div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Values for Validate Command Callback</a></h3> <p>The callback for the <b class="option">-validatecommand</b> option is invoked during the handshake process in order for the application to validate the provided value(s). See below for the possible arguments passed to the callback script. If not specified, OpenSSL will accept all valid certificates and extensions. To reject the value and abort the connection, the callback should return 0. To accept the value and continue the connection, it should return 1. To reject the value, but continue the connection, it should return 2. This callback is new for TclTLS 1.8.</p> |
︙ | ︙ |
Modified doc/tls.man
from [3e3e507451]
to [1296d7b4b7].
︙ | ︙ | |||
78 79 80 81 82 83 84 | [opt_def -cadir [arg directory]] Specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific and can be set at compile time. The default location can be overridden by the [var SSL_CERT_DIR] environment variable. See [sectref "Certificate Validation"] for more details. [opt_def -cafile [arg filename]] | | | | | | | | | | 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | [opt_def -cadir [arg directory]] Specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific and can be set at compile time. The default location can be overridden by the [var SSL_CERT_DIR] environment variable. See [sectref "Certificate Validation"] for more details. [opt_def -cafile [arg filename]] Specifies the file with the Certificate Authority (CA) certificates to use in [const PEM] file format. The default is [file cert.pem], in the OpenSSL directory. The default file can be overridden by the [var SSL_CERT_FILE] environment variable. See [sectref "Certificate Validation"] for more details. [opt_def -castore [arg URI]] Specifies the Uniform Resource Identifier (URI) for the Certificate Authority (CA) store, which may be a single container or a catalog of containers. Starting with OpenSSL 3.2 on MS Windows, set to "[const "org.openssl.winstore://"]" to use the built-in MS Windows Certificate Store. See [sectref "Certificate Validation"] for more details. [opt_def -certfile [arg filename]] Specifies the name of the file with the certificate to use in PEM format as the local (client or server) certificate. It also contains the public key. [opt_def -cert [arg string]] Specifies the certificate to use as a DER encoded string (X.509 DER). [opt_def -cipher [arg string]] Specifies the list of ciphers to use for TLS 1.2 and earlier connections. |
︙ | ︙ | |||
124 125 126 127 128 129 130 | handshake to pass errors, tracing information, and protocol messages. See [sectref "Callback Options"] for more info. [opt_def -dhparams [arg filename]] Specifies the Diffie-Hellman (DH) parameters file. [opt_def -keyfile [arg filename]] | | | > | | | | > | | | 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 | handshake to pass errors, tracing information, and protocol messages. See [sectref "Callback Options"] for more info. [opt_def -dhparams [arg filename]] Specifies the Diffie-Hellman (DH) parameters file. [opt_def -keyfile [arg filename]] Specifies the private key file. The default is to use the file specified by the [arg -certfile] option. [opt_def -key [arg string]] Specifies the private key to use as a DER encoded string (PKCS#1 DER). [opt_def -model [arg channel]] Force this channel to share the same [term SSL_CTX] structure as the specified [arg channel], and therefore share config, callbacks, etc. [opt_def -password [arg callback]] Specifies the callback command to invoke when OpenSSL needs to obtain a password. This is typically used to unlock the private key of a certificate. The callback should return a password string. See [sectref "Callback Options"] for more info. [opt_def -post_handshake [arg bool]] Allow post-handshake session ticket updates. [opt_def -request [arg bool]] Request a certificate from the peer during the SSL handshake. This is needed to do Certificate Validation. Starting in TclTLS 1.8, the default is [const true]. See [sectref "Certificate Validation"] for more details. [opt_def -require [arg bool]] Require a valid certificate from the peer during the SSL handshake. If this is set to true, then [option -request] must also be set to true and a either [option -cadir], [option -cafile], [option -castore], or a platform default must be provided in order to validate against. The default in TclTLS 1.8 and earlier versions is [const false] since not all platforms have certificates to validate against in a form compatible with OpenSSL. See [sectref "Certificate Validation"] for more details. [opt_def -security_level [arg integer]] Specifies the security level (value from 0 to 5). The security level affects the allowed cipher suite encryption algorithms, supported ECC curves, supported signature algorithms, DH parameter sizes, certificate key sizes and signature algorithms. The default is 1 prior to OpenSSL 3.2 and 2 |
︙ | ︙ | |||
498 499 500 501 502 503 504 505 506 507 | Returns the OpenSSL version string. [list_end] [section "Certificate Validation"] [subsection "Summary of command line options"] | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | > | | | > | | | | | | | | > | < | | | | | | > | > | | | | | | > | | | 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 | Returns the OpenSSL version string. [list_end] [section "Certificate Validation"] [subsection "PKI and Certificates"] Using the Public Key Infrastructure (PKI), each user creates a private key that only they know about and a public key they can exchange with others for use in encrypting and decrypting data. The process is the sender encrypts their data using their private key and the receiver's public key. The data is then sent to the receiver. In a similar manner, the receiver uses their private key and the sender's public key to decrypt the data. This provides data integrity, to ensure the data can't be viewed or altered during transport. See the [option -key] and [option -keyfile] options for how to specify the private key. Also see the [option -password] option for how to provide the password. [para] In order to provide authentication, i.e. ensuring someone is who they say they are, the public key and user identification info is stored in a X.509 certificate and that certificate is authenticated (i.e. signed) by a Certificate Authority (CA). Users can then exchange these certificates during the TLS initialization process and check them against the root CA certificates to ensure they are valid. This is handled by OpenSSL via the [option -request] and [option -require] options. See the [option -cadir], [option -cadir], and [option -castore] options for how tp specify where to find the CA certificates. Optionally, in a future release, they can also be checked against the Certificate Revocation List (CRL) of revoked certificates. Certificates can also be self-signed, but they are by default not trusted unless you add them to your certificate store. [para] Typically when visiting web sites, only the client needs to check the server's certificate to ensure it is valid. The server doesn't need to check the client certificate unless you need to authenticate with them to login, etc. See the [option -cert] and [option -certfile] options if you need to provide a certificate. [subsection "Summary of command line options"] The following options are used for peer certificate validation: [list_begin options] [opt_def -cadir [arg directory]] Specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific, but is usually [file "/etc/ssl/certs"] on Linux/Unix systems. The default location can be overridden by the [var SSL_CERT_DIR] environment variable. [opt_def -cafile [arg filename]] Specifies the file with the Certificate Authority (CA) certificates to use in [const PEM] file format. The default is [file cert.pem], in the OpenSSL directory. On Linux/Unix systems, this is usually [file /etc/ssl/ca-bundle.pem]. The default file can be overridden by the [var SSL_CERT_FILE] environment variable. [opt_def -castore [arg URI]] Specifies the Uniform Resource Identifier (URI) for the Certificate Authority (CA) store, which may be a single container or a catalog of containers. Starting with OpenSSL 3.2 on MS Windows, set to "[const "org.openssl.winstore://"]" to use the built-in MS Windows Certificate Store. This store only supports root certificate stores. See [sectref "Certificate Validation"] for more details. [opt_def -request [arg bool]] Request a certificate from the peer during the SSL handshake. This is needed to do Certificate Validation. Starting in TclTLS 1.8, the default is [const true]. In addition, the client can manually inspect and accept or reject each certificate using the [arg -validatecommand] option. [opt_def -require [arg bool]] Require a valid certificate from the peer during the SSL handshake. If this is set to true, then [option -request] must also be set to true and a either [option -cadir], [option -cafile], [option -castore], or a platform default must be provided in order to validate against. The default in TclTLS 1.8 and earlier versions is [const false] since not all platforms have certificates to validate against in a form compatible with OpenSSL. [list_end] [subsection "When are command line options needed?"] In TclTLS 1.8 and earlier versions, certificate validation is [emph NOT] enabled by default. This limitation is due to the lack of a common cross platform database of Certificate Authority (CA) provided certificates to validate against. Many Linux systems natively support OpenSSL and thus have these certificates installed as part of the OS, but MacOS and MS Windows do not. In order to use the [option -require] option, one of the following must be true: [list_begin itemized] [item] On Linux and Unix systems with OpenSSL already installed or if the CA certificates are available in PEM format, and if they are stored in the standard locations, or if the [var SSL_CERT_DIR] or [var SSL_CERT_FILE] environment variables are set, then [option -cadir], [option -cadir], and [option -castore] aren't needed. [item] If OpenSSL is not installed in the default location, or when using Mac OS or MS Windows and OpenSSL is installed, the [var SSL_CERT_DIR] and/or [var SSL_CERT_FILE] environment variables or the one of the [option -cadir], [option -cadir], or [option -castore] options must be defined. [item] On MS Windows, starting in OpenSSL 3.2, it is now possible to access the built-in Windows Certificate Store from OpenSSL. This can utilized by setting the [option -castore] option to "[const org.openssl.winstore://]". [item] If OpenSSL is not installed or the CA certificates are not available in PEM format, the CA certificates must be downloaded and installed with the user software. The CURL team makes them available at [uri "https://curl.se/docs/caextract.html" "CA certificates extracted from Mozilla"] in the [file cacert.pem] file. You must then either set the [var SSL_CERT_DIR] and/or [var SSL_CERT_FILE] environment variables or the [option -cadir] or [option -cafile] options to the CA cert file's install location. It is your responsibility to keep this file up to date. [list_end] |
︙ | ︙ |
Modified doc/tls.n
from [68573cb13e]
to [b5c12e6dd7].
︙ | ︙ | |||
355 356 357 358 359 360 361 | \fB-cadir\fR \fIdirectory\fR Specifies the directory where the Certificate Authority (CA) certificates are stored\&. The default is platform specific and can be set at compile time\&. The default location can be overridden by the \fBSSL_CERT_DIR\fR environment variable\&. See \fBCertificate Validation\fR for more details\&. .TP \fB-cafile\fR \fIfilename\fR | | | | | | | | | | 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 | \fB-cadir\fR \fIdirectory\fR Specifies the directory where the Certificate Authority (CA) certificates are stored\&. The default is platform specific and can be set at compile time\&. The default location can be overridden by the \fBSSL_CERT_DIR\fR environment variable\&. See \fBCertificate Validation\fR for more details\&. .TP \fB-cafile\fR \fIfilename\fR Specifies the file with the Certificate Authority (CA) certificates to use in \fBPEM\fR file format\&. The default is "\fIcert\&.pem\fR", in the OpenSSL directory\&. The default file can be overridden by the \fBSSL_CERT_FILE\fR environment variable\&. See \fBCertificate Validation\fR for more details\&. .TP \fB-castore\fR \fIURI\fR Specifies the Uniform Resource Identifier (URI) for the Certificate Authority (CA) store, which may be a single container or a catalog of containers\&. Starting with OpenSSL 3\&.2 on MS Windows, set to "\fBorg\&.openssl\&.winstore://\fR" to use the built-in MS Windows Certificate Store\&. See \fBCertificate Validation\fR for more details\&. .TP \fB-certfile\fR \fIfilename\fR Specifies the name of the file with the certificate to use in PEM format as the local (client or server) certificate\&. It also contains the public key\&. .TP \fB-cert\fR \fIstring\fR Specifies the certificate to use as a DER encoded string (X\&.509 DER)\&. .TP \fB-cipher\fR \fIstring\fR Specifies the list of ciphers to use for TLS 1\&.2 and earlier connections\&. |
︙ | ︙ | |||
401 402 403 404 405 406 407 | handshake to pass errors, tracing information, and protocol messages\&. See \fBCallback Options\fR for more info\&. .TP \fB-dhparams\fR \fIfilename\fR Specifies the Diffie-Hellman (DH) parameters file\&. .TP \fB-keyfile\fR \fIfilename\fR | | | | > | | | > | | | 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 | handshake to pass errors, tracing information, and protocol messages\&. See \fBCallback Options\fR for more info\&. .TP \fB-dhparams\fR \fIfilename\fR Specifies the Diffie-Hellman (DH) parameters file\&. .TP \fB-keyfile\fR \fIfilename\fR Specifies the private key file\&. The default is to use the file specified by the \fI-certfile\fR option\&. .TP \fB-key\fR \fIstring\fR Specifies the private key to use as a DER encoded string (PKCS#1 DER)\&. .TP \fB-model\fR \fIchannel\fR Force this channel to share the same \fISSL_CTX\fR structure as the specified \fIchannel\fR, and therefore share config, callbacks, etc\&. .TP \fB-password\fR \fIcallback\fR Specifies the callback command to invoke when OpenSSL needs to obtain a password\&. This is typically used to unlock the private key of a certificate\&. The callback should return a password string\&. See \fBCallback Options\fR for more info\&. .TP \fB-post_handshake\fR \fIbool\fR Allow post-handshake session ticket updates\&. .TP \fB-request\fR \fIbool\fR Request a certificate from the peer during the SSL handshake\&. This is needed to do Certificate Validation\&. Starting in TclTLS 1\&.8, the default is \fBtrue\fR\&. See \fBCertificate Validation\fR for more details\&. .TP \fB-require\fR \fIbool\fR Require a valid certificate from the peer during the SSL handshake\&. If this is set to true, then \fB-request\fR must also be set to true and a either \fB-cadir\fR, \fB-cafile\fR, \fB-castore\fR, or a platform default must be provided in order to validate against\&. The default in TclTLS 1\&.8 and earlier versions is \fBfalse\fR since not all platforms have certificates to validate against in a form compatible with OpenSSL\&. See \fBCertificate Validation\fR for more details\&. .TP \fB-security_level\fR \fIinteger\fR Specifies the security level (value from 0 to 5)\&. The security level affects the allowed cipher suite encryption algorithms, supported ECC curves, supported signature algorithms, DH parameter sizes, certificate key sizes and signature algorithms\&. The default is 1 prior to OpenSSL 3\&.2 and 2 |
︙ | ︙ | |||
750 751 752 753 754 755 756 757 | \fBssl2\fR, \fBssl3\fR, \fBtls1\fR, \fBtls1\&.1\fR, \fBtls1\&.2\fR, and \fBtls1\&.3\fR\&. Exact list depends on OpenSSL version and compile time flags\&. .TP \fBtls::version\fR Returns the OpenSSL version string\&. .PP .SH "CERTIFICATE VALIDATION" .SS "SUMMARY OF COMMAND LINE OPTIONS" | > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | > | | | > | | | | | | | | > | < | | | | | | > | > | | | | | | > | | | 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 | \fBssl2\fR, \fBssl3\fR, \fBtls1\fR, \fBtls1\&.1\fR, \fBtls1\&.2\fR, and \fBtls1\&.3\fR\&. Exact list depends on OpenSSL version and compile time flags\&. .TP \fBtls::version\fR Returns the OpenSSL version string\&. .PP .SH "CERTIFICATE VALIDATION" .SS "PKI AND CERTIFICATES" Using the Public Key Infrastructure (PKI), each user creates a private key that only they know about and a public key they can exchange with others for use in encrypting and decrypting data\&. The process is the sender encrypts their data using their private key and the receiver's public key\&. The data is then sent to the receiver\&. In a similar manner, the receiver uses their private key and the sender's public key to decrypt the data\&. This provides data integrity, to ensure the data can't be viewed or altered during transport\&. See the \fB-key\fR and \fB-keyfile\fR options for how to specify the private key\&. Also see the \fB-password\fR option for how to provide the password\&. .PP In order to provide authentication, i\&.e\&. ensuring someone is who they say they are, the public key and user identification info is stored in a X\&.509 certificate and that certificate is authenticated (i\&.e\&. signed) by a Certificate Authority (CA)\&. Users can then exchange these certificates during the TLS initialization process and check them against the root CA certificates to ensure they are valid\&. This is handled by OpenSSL via the \fB-request\fR and \fB-require\fR options\&. See the \fB-cadir\fR, \fB-cadir\fR, and \fB-castore\fR options for how tp specify where to find the CA certificates\&. Optionally, in a future release, they can also be checked against the Certificate Revocation List (CRL) of revoked certificates\&. Certificates can also be self-signed, but they are by default not trusted unless you add them to your certificate store\&. .PP Typically when visiting web sites, only the client needs to check the server's certificate to ensure it is valid\&. The server doesn't need to check the client certificate unless you need to authenticate with them to login, etc\&. See the \fB-cert\fR and \fB-certfile\fR options if you need to provide a certificate\&. .SS "SUMMARY OF COMMAND LINE OPTIONS" The following options are used for peer certificate validation: .TP \fB-cadir\fR \fIdirectory\fR Specifies the directory where the Certificate Authority (CA) certificates are stored\&. The default is platform specific, but is usually "\fI/etc/ssl/certs\fR" on Linux/Unix systems\&. The default location can be overridden by the \fBSSL_CERT_DIR\fR environment variable\&. .TP \fB-cafile\fR \fIfilename\fR Specifies the file with the Certificate Authority (CA) certificates to use in \fBPEM\fR file format\&. The default is "\fIcert\&.pem\fR", in the OpenSSL directory\&. On Linux/Unix systems, this is usually "\fI/etc/ssl/ca-bundle\&.pem\fR"\&. The default file can be overridden by the \fBSSL_CERT_FILE\fR environment variable\&. .TP \fB-castore\fR \fIURI\fR Specifies the Uniform Resource Identifier (URI) for the Certificate Authority (CA) store, which may be a single container or a catalog of containers\&. Starting with OpenSSL 3\&.2 on MS Windows, set to "\fBorg\&.openssl\&.winstore://\fR" to use the built-in MS Windows Certificate Store\&. This store only supports root certificate stores\&. See \fBCertificate Validation\fR for more details\&. .TP \fB-request\fR \fIbool\fR Request a certificate from the peer during the SSL handshake\&. This is needed to do Certificate Validation\&. Starting in TclTLS 1\&.8, the default is \fBtrue\fR\&. In addition, the client can manually inspect and accept or reject each certificate using the \fI-validatecommand\fR option\&. .TP \fB-require\fR \fIbool\fR Require a valid certificate from the peer during the SSL handshake\&. If this is set to true, then \fB-request\fR must also be set to true and a either \fB-cadir\fR, \fB-cafile\fR, \fB-castore\fR, or a platform default must be provided in order to validate against\&. The default in TclTLS 1\&.8 and earlier versions is \fBfalse\fR since not all platforms have certificates to validate against in a form compatible with OpenSSL\&. .PP .SS "WHEN ARE COMMAND LINE OPTIONS NEEDED?" In TclTLS 1\&.8 and earlier versions, certificate validation is \fINOT\fR enabled by default\&. This limitation is due to the lack of a common cross platform database of Certificate Authority (CA) provided certificates to validate against\&. Many Linux systems natively support OpenSSL and thus have these certificates installed as part of the OS, but MacOS and MS Windows do not\&. In order to use the \fB-require\fR option, one of the following must be true: .IP \(bu On Linux and Unix systems with OpenSSL already installed or if the CA certificates are available in PEM format, and if they are stored in the standard locations, or if the \fBSSL_CERT_DIR\fR or \fBSSL_CERT_FILE\fR environment variables are set, then \fB-cadir\fR, \fB-cadir\fR, and \fB-castore\fR aren't needed\&. .IP \(bu If OpenSSL is not installed in the default location, or when using Mac OS or MS Windows and OpenSSL is installed, the \fBSSL_CERT_DIR\fR and/or \fBSSL_CERT_FILE\fR environment variables or the one of the \fB-cadir\fR, \fB-cadir\fR, or \fB-castore\fR options must be defined\&. .IP \(bu On MS Windows, starting in OpenSSL 3\&.2, it is now possible to access the built-in Windows Certificate Store from OpenSSL\&. This can utilized by setting the \fB-castore\fR option to "\fBorg\&.openssl\&.winstore://\fR"\&. .IP \(bu If OpenSSL is not installed or the CA certificates are not available in PEM format, the CA certificates must be downloaded and installed with the user software\&. The CURL team makes them available at \fICA certificates extracted from Mozilla\fR [https://curl\&.se/docs/caextract\&.html] in the "\fIcacert\&.pem\fR" file\&. You must then either set the \fBSSL_CERT_DIR\fR and/or \fBSSL_CERT_FILE\fR environment variables or the \fB-cadir\fR or \fB-cafile\fR options to the CA cert file's install location\&. It is your responsibility to keep this file up to date\&. .PP .SH "CALLBACK OPTIONS" |
︙ | ︙ |
Modified generic/tls.c
from [6533cb2d9b]
to [6556ea2daa].
︙ | ︙ | |||
3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 | statePtr->password = NULL; } if (statePtr->vcmd) { Tcl_DecrRefCount(statePtr->vcmd); statePtr->vcmd = NULL; } if (statePtr->protos) { ckfree(statePtr->protos); statePtr->protos = NULL; } if (statePtr->bio) { /* This will call SSL_shutdown. Bug 1414045 */ | > > | > | > > | 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 | statePtr->password = NULL; } if (statePtr->vcmd) { Tcl_DecrRefCount(statePtr->vcmd); statePtr->vcmd = NULL; } /* Remove list of ALPN protocols */ if (statePtr->protos) { ckfree(statePtr->protos); statePtr->protos = NULL; } /* BIO_free_all() frees up an entire BIO chain */ if (statePtr->bio) { /* This will call SSL_shutdown. Bug 1414045 */ dprintf("BIO_free(%p)", statePtr->bio); BIO_free_all(statePtr->bio); statePtr->bio = NULL; } /* Free SSL context and statePtr->p_bio */ if (statePtr->ssl) { dprintf("SSL_free(%p) and p_bio(%p)", statePtr->ssl, statePtr->p_bio); SSL_free(statePtr->ssl); statePtr->ssl = NULL; } /* Free CTX context */ if (statePtr->ctx) { dprintf("SSL_CTX_free(%p)", statePtr->ctx); SSL_CTX_free(statePtr->ctx); statePtr->ctx = NULL; } dprintf("Returning"); } |
︙ | ︙ |
Modified generic/tlsBIO.c
from [82977b2388]
to [201a06bc4e].
1 2 3 4 5 6 7 8 9 10 11 | /* * Provides Custom BIO layer to interface OpenSSL with TCL. These functions * directly interface between the TCL IO channel and BIO buffers. * * Copyright (C) 1997-2000 Matt Newman <[email protected]> * Copyright (C) 2024 Brian O'Hagan * */ /* tlsBIO.c tlsIO.c | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | /* * Provides Custom BIO layer to interface OpenSSL with TCL. These functions * directly interface between the TCL IO channel and BIO buffers. * * Copyright (C) 1997-2000 Matt Newman <[email protected]> * Copyright (C) 2024 Brian O'Hagan * */ /* tlsBIO.c tlsIO.c +------+ +---+ +---+ | |Tcl_WriteRaw<--BioOutput|SSL|BIO_write<--TlsOutputProc<--Write| | |socket| <encrypted> |BIO| <unencrypted> |App| | |Tcl_ReadRaw --> BioInput| |BIO_Read -->TlsInputProc --> Read| | +------+ +---+ +---+ */ #include "tlsInt.h" #include <openssl/bio.h> /* Define BIO methods structure */ static BIO_METHOD *BioMethods = NULL; |
︙ | ︙ | |||
57 58 59 60 61 62 63 | return res; } /* *----------------------------------------------------------------------------- * | | | | > | | 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 | return res; } /* *----------------------------------------------------------------------------- * * BioOutput -- * * This function is used to read encrypted data from the BIO and write it * into the socket. This function will be called in response to the * application calling the BIO_write_ex() or BIO_write() functions. * * Results: * Returns the number of bytes written to channel, 0 for EOF, or -1 for * error. * * Side effects: * Writes BIO data to channel. * *----------------------------------------------------------------------------- */ static int BioOutput(BIO *bio, const char *buf, int bufLen) { Tcl_Size ret; int is_eof, tclErrno; State *statePtr = (State *) BIO_get_data(bio); Tcl_Channel chan = Tls_GetParent(statePtr, 0); dprintf("[chan=%p] BioOutput(bio=%p, buf=%p, len=%d)", (void *)chan, (void *) bio, buf, bufLen); BIO_clear_retry_flags(bio); Tcl_SetErrno(0); /* Write data to underlying channel */ ret = Tcl_WriteRaw(chan, buf, (Tcl_Size) bufLen); is_eof = Tcl_Eof(chan); tclErrno = Tcl_GetErrno(); dprintf("[chan=%p] BioOutput(%d) -> %" TCL_SIZE_MODIFIER "d [tclEof=%d; tclErrno=%d: %s]", (void *) chan, bufLen, ret, is_eof, tclErrno, Tcl_ErrnoMsg(tclErrno)); if (ret > 0) { dprintf("Successfully wrote %" TCL_SIZE_MODIFIER "d bytes of data", ret); } else if (ret == 0) { if (is_eof) { |
︙ | ︙ | |||
121 122 123 124 125 126 127 | BIO_set_retry_write(bio); } else { dprintf("Unexpected error: %i=%s", tclErrno, Tcl_ErrnoMsg(tclErrno)); } } | | | | 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | BIO_set_retry_write(bio); } else { dprintf("Unexpected error: %i=%s", tclErrno, Tcl_ErrnoMsg(tclErrno)); } } dprintf("BioOutput returning %" TCL_SIZE_MODIFIER "d", ret); return (int) ret; } /* *----------------------------------------------------------------------------- * * BioInput -- * * This function is used to read encrypted data from the socket and * write it into the BIO. This function will be called in response to the * application calling the BIO_read_ex() or BIO_read() functions. * * Results: * Returns the number of bytes read from channel, 0 for EOF, or -1 for |
︙ | ︙ | |||
151 152 153 154 155 156 157 | * returns the number of bytes which have been processed, buffered, and are * available inside ssl for immediate read. SSL_has_pending() returns 1 if * data is buffered (whether processed or unprocessed) and 0 otherwise. * *----------------------------------------------------------------------------- */ | | | > | | 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 | * returns the number of bytes which have been processed, buffered, and are * available inside ssl for immediate read. SSL_has_pending() returns 1 if * data is buffered (whether processed or unprocessed) and 0 otherwise. * *----------------------------------------------------------------------------- */ static int BioInput(BIO *bio, char *buf, int bufLen) { Tcl_Size ret = 0; int is_eof, tclErrno, is_blocked; State *statePtr = (State *) BIO_get_data(bio); Tcl_Channel chan = Tls_GetParent(statePtr, 0); dprintf("[chan=%p] BioInput(bio=%p, buf=%p, len=%d)", (void *) chan, (void *) bio, buf, bufLen); if (buf == NULL || bufLen <= 0) { return 0; } BIO_clear_retry_flags(bio); Tcl_SetErrno(0); /* Read data from underlying channel */ ret = Tcl_ReadRaw(chan, buf, (Tcl_Size) bufLen); is_eof = Tcl_Eof(chan); tclErrno = Tcl_GetErrno(); is_blocked = Tcl_InputBlocked(chan); dprintf("[chan=%p] BioInput(%d) -> %" TCL_SIZE_MODIFIER "d [tclEof=%d; blocked=%d; tclErrno=%d: %s]", (void *) chan, bufLen, ret, is_eof, is_blocked, tclErrno, Tcl_ErrnoMsg(tclErrno)); if (ret > 0) { dprintf("Successfully read %" TCL_SIZE_MODIFIER "d bytes of data", ret); } else if (ret == 0) { if (is_eof) { |
︙ | ︙ | |||
202 203 204 205 206 207 208 | BIO_set_retry_read(bio); } else { dprintf("Unexpected error: %i=%s", tclErrno, Tcl_ErrnoMsg(tclErrno)); } } | | | 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | BIO_set_retry_read(bio); } else { dprintf("Unexpected error: %i=%s", tclErrno, Tcl_ErrnoMsg(tclErrno)); } } dprintf("BioInput returning %" TCL_SIZE_MODIFIER "d", ret); return (int) ret; } /* *----------------------------------------------------------------------------- * * BioPuts -- |
︙ | ︙ | |||
227 228 229 230 231 232 233 | * *----------------------------------------------------------------------------- */ static int BioPuts(BIO *bio, const char *str) { dprintf("BioPuts(%p) \"%s\"", bio, str); | | | 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 | * *----------------------------------------------------------------------------- */ static int BioPuts(BIO *bio, const char *str) { dprintf("BioPuts(%p) \"%s\"", bio, str); return BioOutput(bio, str, (int) strlen(str)); } /* *----------------------------------------------------------------------------- * * BioCtrl -- * |
︙ | ︙ | |||
318 319 320 321 322 323 324 | break; case BIO_CTRL_FLUSH: /* opt - Flush any buffered output. Implements BIO_flush. */ dprintf("Got BIO_CTRL_FLUSH"); /* Use Tcl_WriteRaw instead of Tcl_Flush to operate on right chan in stack */ /* Returns 1 for success, <=0 for error/retry. */ ret = ((chan) && (Tcl_WriteRaw(chan, "", 0) >= 0) ? 1 : -1); | | | 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 | break; case BIO_CTRL_FLUSH: /* opt - Flush any buffered output. Implements BIO_flush. */ dprintf("Got BIO_CTRL_FLUSH"); /* Use Tcl_WriteRaw instead of Tcl_Flush to operate on right chan in stack */ /* Returns 1 for success, <=0 for error/retry. */ ret = ((chan) && (Tcl_WriteRaw(chan, "", 0) >= 0) ? 1 : -1); /*ret = BioOutput(bio, NULL, 0);*/ break; case BIO_CTRL_DUP: /* man - extra stuff for 'duped' BIO. Implements BIO_dup_state */ dprintf("Got BIO_CTRL_DUP"); ret = 1; break; case BIO_CTRL_WPENDING: |
︙ | ︙ | |||
491 492 493 494 495 496 497 | BioMethods = BIO_meth_new(BIO_TYPE_BIO, "tcl"); if (BioMethods == NULL) { dprintf("Memory allocation error"); return NULL; } /* Not used BIO_meth_set_write_ex */ | | | | | | > | > | > | 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 | BioMethods = BIO_meth_new(BIO_TYPE_BIO, "tcl"); if (BioMethods == NULL) { dprintf("Memory allocation error"); return NULL; } /* Not used BIO_meth_set_write_ex */ BIO_meth_set_write(BioMethods, BioOutput); /* Not used BIO_meth_set_read_ex */ BIO_meth_set_read(BioMethods, BioInput); BIO_meth_set_puts(BioMethods, BioPuts); BIO_meth_set_ctrl(BioMethods, BioCtrl); BIO_meth_set_create(BioMethods, BioNew); BIO_meth_set_destroy(BioMethods, BioFree); } if (statePtr == NULL) { dprintf("Asked to setup a NULL state, just creating the initial configuration"); return NULL; } #ifdef TCLTLS_SSL_USE_FASTPATH /* * If the channel can be mapped back to a file descriptor, just use the file * descriptor with the SSL library since it will likely be optimized for this. */ parentChannel = Tls_GetParent(statePtr, 0); parentChannelType = Tcl_GetChannelType(parentChannel); validParentChannelFd = 0; if (strcmp(parentChannelType->typeName, "tcp") == 0) { void *parentChannelFdIn_p, *parentChannelFdOut_p; int tclGetChannelHandleRet; tclGetChannelHandleRet = Tcl_GetChannelHandle(parentChannel, TCL_READABLE, &parentChannelFdIn_p); if (tclGetChannelHandleRet == TCL_OK) { tclGetChannelHandleRet = Tcl_GetChannelHandle(parentChannel, TCL_WRITABLE, &parentChannelFdOut_p); if (tclGetChannelHandleRet == TCL_OK) { parentChannelFdIn = PTR2INT(parentChannelFdIn_p); parentChannelFdOut = PTR2INT(parentChannelFdOut_p); if (parentChannelFdIn == parentChannelFdOut) { parentChannelFd = parentChannelFdIn; validParentChannelFd = 1; } } } } if (validParentChannelFd) { dprintf("We found a shortcut, this channel is backed by a socket: %i", parentChannelFdIn); bio = BIO_new_socket(parentChannelFd, flags); statePtr->flags |= TLS_TCL_FASTPATH; BIO_set_data(bio, statePtr); BIO_set_shutdown(bio, flags); BIO_set_init(bio, 1); return bio; } |
︙ | ︙ |
Modified generic/tlsIO.c
from [5d7eb66752]
to [0f8d7086c3].
︙ | ︙ | |||
14 15 16 17 18 19 20 | * tclSSL (Colin McCormack, Shared Technology) * SSLtcl (Peter Antman) * */ /* tlsBIO.c tlsIO.c | | | | | | | 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | * tclSSL (Colin McCormack, Shared Technology) * SSLtcl (Peter Antman) * */ /* tlsBIO.c tlsIO.c +------+ +---+ +---+ | |Tcl_WriteRaw<--BioOutput|SSL|BIO_write<--TlsOutputProc<--Write| | |socket| <encrypted> |BIO| <unencrypted> |App| | |Tcl_ReadRaw --> BioInput| |BIO_Read -->TlsInputProc --> Read| | +------+ +---+ +---+ */ #include "tlsInt.h" #include <errno.h> /* *----------------------------------------------------------------------------- |
︙ | ︙ | |||
41 42 43 44 45 46 47 | * 0 if successful or POSIX error code if failed. * * Side effects: * Sets the device into blocking or nonblocking mode. * *----------------------------------------------------------------------------- */ | | > > > | | < | > > > | | > | | > | | | 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | * 0 if successful or POSIX error code if failed. * * Side effects: * Sets the device into blocking or nonblocking mode. * *----------------------------------------------------------------------------- */ static int TlsBlockModeProc( ClientData instanceData, /* Connection state info */ int mode) /* Blocking or non-blocking mode */ { State *statePtr = (State *) instanceData; if (mode == TCL_MODE_NONBLOCKING) { statePtr->flags |= TLS_TCL_ASYNC; } else { statePtr->flags &= ~(TLS_TCL_ASYNC); } return 0; } /* *----------------------------------------------------------------------------- * * TlsCloseProc -- * * This procedure is invoked by the generic IO level to perform channel * type specific cleanup when a SSL socket based channel is closed. Called * by the generic I/O layer whenever the Tcl_Close() function is used. * * Results: * 0 if successful or POSIX error code if failed. * * Side effects: * Closes the socket of the channel. * *----------------------------------------------------------------------------- */ static int TlsCloseProc( ClientData instanceData, /* Connection state info */ Tcl_Interp *interp) /* Tcl interpreter to report errors to */ { State *statePtr = (State *) instanceData; dprintf("TlsCloseProc(%p)", (void *) statePtr); /* Send shutdown notification. Will return 0 while in process, then 1 when complete. Only closes the write direction of the connection; the read direction is closed by the peer. Does not affect socket state. Don't call after fatal error. */ if (statePtr->ssl != NULL && !(statePtr->flags & TLS_TCL_HANDSHAKE_FAILED)) { BIO_flush(statePtr->bio); SSL_shutdown(statePtr->ssl); } /* Tls_Free calls Tls_Clean */ Tcl_EventuallyFree((ClientData)statePtr, Tls_Free); return 0; } /* *----------------------------------------------------------------------------- * * TlsClose2Proc -- * * Similar to TlsCloseProc, but allows for separate close read and write * side of channel. * *----------------------------------------------------------------------------- */ static int TlsClose2Proc( ClientData instanceData, /* Connection state info */ Tcl_Interp *interp, /* Tcl interpreter to report errors to */ int flags) /* Flags to close read/write side of channel */ { State *statePtr = (State *) instanceData; dprintf("TlsClose2Proc(%p)", (void *) statePtr); if ((flags & (TCL_CLOSE_READ|TCL_CLOSE_WRITE)) == 0) { return TlsCloseProc(instanceData, interp); |
︙ | ︙ | |||
128 129 130 131 132 133 134 | * 1 if successful, 0 if wait for connect, and -1 if failed. * * Side effects: * Issues SSL_accept or SSL_connect * *----------------------------------------------------------------------------- */ | | > > > > | 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | * 1 if successful, 0 if wait for connect, and -1 if failed. * * Side effects: * Issues SSL_accept or SSL_connect * *----------------------------------------------------------------------------- */ int Tls_WaitForConnect( State *statePtr, /* Connection state info */ int *errorCodePtr, /* Storage for error code to return */ int handshakeFailureIsPermanent) /* Is the connect failure permanent */ { unsigned long backingError; int err, rc = 0; int bioShouldRetry; *errorCodePtr = 0; dprintf("WaitForConnect(%p)", (void *) statePtr); dprintFlags(statePtr); |
︙ | ︙ | |||
237 238 239 240 241 242 243 | case SSL_ERROR_NONE: /* The TLS/SSL I/O operation completed successfully */ dprintf("The connection is good"); *errorCodePtr = 0; break; case SSL_ERROR_SSL: | | | > > | | 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 | case SSL_ERROR_NONE: /* The TLS/SSL I/O operation completed successfully */ dprintf("The connection is good"); *errorCodePtr = 0; break; case SSL_ERROR_SSL: /* A non-recoverable, fatal error in the SSL library occurred, usually a protocol error. This includes certificate validation errors. */ dprintf("SSL_ERROR_SSL: Got permanent fatal SSL error, aborting immediately"); if (SSL_get_verify_result(statePtr->ssl) != X509_V_OK) { Tls_Error(statePtr, X509_verify_cert_error_string(SSL_get_verify_result(statePtr->ssl))); } if (backingError != 0) { Tls_Error(statePtr, ERR_reason_error_string(backingError)); } statePtr->flags |= TLS_TCL_HANDSHAKE_FAILED; *errorCodePtr = ECONNABORTED; return -1; |
︙ | ︙ | |||
280 281 282 283 284 285 286 | Tls_Error(statePtr, ERR_reason_error_string(backingError)); } statePtr->flags |= TLS_TCL_HANDSHAKE_FAILED; return -1; case SSL_ERROR_ZERO_RETURN: | | > | | > | | > | 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 | Tls_Error(statePtr, ERR_reason_error_string(backingError)); } statePtr->flags |= TLS_TCL_HANDSHAKE_FAILED; return -1; case SSL_ERROR_ZERO_RETURN: /* Peer has closed the connection by sending the close_notify alert. Can't read, but can write. Need to return an EOF, so channel is closed which will send an SSL_shutdown(). */ dprintf("SSL_ERROR_ZERO_RETURN: Connect returned an invalid value..."); *errorCodePtr = ECONNRESET; Tls_Error(statePtr, "Peer has closed the connection for writing by sending the close_notify alert"); return -1; case SSL_ERROR_WANT_READ: /* More data must be read from the underlying BIO layer in order to complete the actual SSL_*() operation. */ dprintf("SSL_ERROR_WANT_READ"); BIO_set_retry_read(statePtr->bio); *errorCodePtr = EAGAIN; dprintf("ERR(SSL_ERROR_WANT_READ, EAGAIN) "); statePtr->want |= TCL_READABLE; return 0; case SSL_ERROR_WANT_WRITE: /* There is data in the SSL buffer that must be written to the underlying BIO in order to complete the SSL_*() operation. */ dprintf("SSL_ERROR_WANT_WRITE"); BIO_set_retry_write(statePtr->bio); *errorCodePtr = EAGAIN; dprintf("ERR(SSL_ERROR_WANT_WRITE, EAGAIN) "); statePtr->want |= TCL_WRITABLE; return 0; |
︙ | ︙ | |||
324 325 326 327 328 329 330 | BIO_set_retry_special(statePtr->bio); BIO_set_retry_reason(statePtr->bio, BIO_RR_ACCEPT); *errorCodePtr = EAGAIN; dprintf("ERR(SSL_ERROR_WANT_ACCEPT, EAGAIN) "); return 0; case SSL_ERROR_WANT_X509_LOOKUP: | | > | > | > | > | > | > | 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 | BIO_set_retry_special(statePtr->bio); BIO_set_retry_reason(statePtr->bio, BIO_RR_ACCEPT); *errorCodePtr = EAGAIN; dprintf("ERR(SSL_ERROR_WANT_ACCEPT, EAGAIN) "); return 0; case SSL_ERROR_WANT_X509_LOOKUP: /* Application callback set by SSL_CTX_set_client_cert_cb has asked to be called again. The operation did not complete because an application callback set by SSL_CTX_set_client_cert_cb() has asked to be called again. */ dprintf("SSL_ERROR_WANT_X509_LOOKUP"); BIO_set_retry_special(statePtr->bio); BIO_set_retry_reason(statePtr->bio, BIO_RR_SSL_X509_LOOKUP); *errorCodePtr = EAGAIN; dprintf("ERR(SSL_ERROR_WANT_X509_LOOKUP, EAGAIN) "); return 0; case SSL_ERROR_WANT_ASYNC: /* Used with flag SSL_MODE_ASYNC, op didn't complete because an async engine is still processing data */ case SSL_ERROR_WANT_ASYNC_JOB: /* The asynchronous job could not be started because there were no async jobs available in the pool. */ case SSL_ERROR_WANT_CLIENT_HELLO_CB: /* The operation did not complete because an application callback set by SSL_CTX_set_client_hello_cb() has asked to be called again. */ #if OPENSSL_VERSION_NUMBER >= 0x30000000L case SSL_ERROR_WANT_RETRY_VERIFY: /* The operation did not complete because a certificate verification callback has asked to be called again via SSL_set_retry_verify(3). */ #endif default: /* The operation did not complete and should be retried later. */ dprintf("Operation did not complete, call function again later"); *errorCodePtr = EAGAIN; dprintf("ERR(Other, EAGAIN) "); return 0; |
︙ | ︙ | |||
381 382 383 384 385 386 387 | * * Data is received in whole blocks known as records from the peer. A whole * record is processed (e.g. decrypted) in one go and is buffered by OpenSSL * until it is read by the application via a call to SSL_read. * *----------------------------------------------------------------------------- */ | | > > > > > | > | 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 | * * Data is received in whole blocks known as records from the peer. A whole * record is processed (e.g. decrypted) in one go and is buffered by OpenSSL * until it is read by the application via a call to SSL_read. * *----------------------------------------------------------------------------- */ static int TlsInputProc( ClientData instanceData, /* Connection state info */ char *buf, /* Buffer to store data read from BIO */ int bufSize, /* Buffer size in bytes */ int *errorCodePtr) /* Storage for error code to return */ { unsigned long backingError; State *statePtr = (State *) instanceData; int bytesRead, err; *errorCodePtr = 0; dprintf("Read(%d)", bufSize); /* Abort if the user verify callback is still running to avoid triggering * another call before the current one is complete. */ if (statePtr->flags & TLS_TCL_CALLBACK) { dprintf("Callback is running, reading 0 bytes"); return 0; } /* If not initialized, do connect */ /* Can also check SSL_is_init_finished(ssl) */ |
︙ | ︙ | |||
472 473 474 475 476 477 478 | case SSL_ERROR_NONE: /* I/O operation completed */ dprintf("SSL_ERROR_NONE"); dprintBuffer(buf, bytesRead); break; case SSL_ERROR_SSL: | | > > | | > | > > | | > | > | | > | 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 | case SSL_ERROR_NONE: /* I/O operation completed */ dprintf("SSL_ERROR_NONE"); dprintBuffer(buf, bytesRead); break; case SSL_ERROR_SSL: /* A non-recoverable, fatal error in the SSL library occurred, usually a protocol error. */ dprintf("SSL error, indicating that the connection has been aborted"); if (backingError != 0) { Tls_Error(statePtr, ERR_reason_error_string(backingError)); } else if (SSL_get_verify_result(statePtr->ssl) != X509_V_OK) { Tls_Error(statePtr, X509_verify_cert_error_string(SSL_get_verify_result(statePtr->ssl))); } else { Tls_Error(statePtr, "Unknown SSL error"); } *errorCodePtr = ECONNABORTED; bytesRead = -1; #if OPENSSL_VERSION_NUMBER >= 0x30000000L /* Unexpected EOF from the peer for OpenSSL 3.0+ */ if (ERR_GET_REASON(backingError) == SSL_R_UNEXPECTED_EOF_WHILE_READING) { dprintf("(Unexpected) EOF reached") *errorCodePtr = 0; bytesRead = 0; Tls_Error(statePtr, "EOF reached"); } #endif break; case SSL_ERROR_WANT_READ: /* Operation did not complete due to not enough data was available. Retry again later. */ dprintf("Got SSL_ERROR_WANT_READ, mapping this to EAGAIN"); *errorCodePtr = EAGAIN; bytesRead = -1; statePtr->want |= TCL_READABLE; BIO_set_retry_read(statePtr->bio); break; case SSL_ERROR_WANT_WRITE: /* Operation did not complete due to unable to send all data to the BIO. Retry again later. */ dprintf("Got SSL_ERROR_WANT_WRITE, mapping this to EAGAIN"); *errorCodePtr = EAGAIN; bytesRead = -1; statePtr->want |= TCL_WRITABLE; BIO_set_retry_write(statePtr->bio); break; case SSL_ERROR_WANT_X509_LOOKUP: /* Operation didn't complete since application callback set by SSL_CTX_set_client_cert_cb() asked to be called again. */ dprintf("Got SSL_ERROR_WANT_X509_LOOKUP, mapping it to EAGAIN"); *errorCodePtr = EAGAIN; bytesRead = -1; break; case SSL_ERROR_SYSCALL: /* Some non-recoverable, fatal I/O error occurred */ dprintf("SSL_ERROR_SYSCALL"); if (backingError == 0 && bytesRead == 0) { /* Unexpected EOF from the peer for OpenSSL 1.1 */ dprintf("(Unexpected) EOF reached") *errorCodePtr = 0; bytesRead = 0; Tls_Error(statePtr, "EOF reached"); } else if (backingError == 0 && bytesRead == -1) { dprintf("I/O error occurred (errno = %lu)", (unsigned long) Tcl_GetErrno()); *errorCodePtr = Tcl_GetErrno(); bytesRead = -1; Tls_Error(statePtr, Tcl_ErrnoMsg(*errorCodePtr)); } else { dprintf("I/O error occurred (backingError = %lu)", backingError); *errorCodePtr = Tcl_GetErrno(); bytesRead = -1; Tls_Error(statePtr, ERR_reason_error_string(backingError)); } break; case SSL_ERROR_ZERO_RETURN: /* Peer has closed the connection by sending the close_notify alert. Can't read, but can write. Need to return an EOF, so channel is closed which will send an SSL_shutdown(). */ dprintf("Got SSL_ERROR_ZERO_RETURN, this means an EOF has been reached"); bytesRead = 0; *errorCodePtr = 0; Tls_Error(statePtr, "Peer has closed the connection for writing by sending the close_notify alert"); break; case SSL_ERROR_WANT_ASYNC: /* Used with flag SSL_MODE_ASYNC, operation didn't complete because an async engine is still processing data. */ dprintf("Got SSL_ERROR_WANT_ASYNC, mapping this to EAGAIN"); *errorCodePtr = EAGAIN; bytesRead = -1; break; default: dprintf("Unknown error (err = %i), mapping to EOF", err); |
︙ | ︙ | |||
591 592 593 594 595 596 597 | * to a POSIX error code if an error occurred, or 0 if none. * * Side effects: * Writes output on the output device of the channel. * *----------------------------------------------------------------------------- */ | | > > > > > | > | > | 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 | * to a POSIX error code if an error occurred, or 0 if none. * * Side effects: * Writes output on the output device of the channel. * *----------------------------------------------------------------------------- */ static int TlsOutputProc( ClientData instanceData, /* Connection state info */ const char *buf, /* Buffer with data to write to BIO */ int toWrite, /* Size of data to write in bytes */ int *errorCodePtr) /* Storage for error code to return */ { unsigned long backingError; State *statePtr = (State *) instanceData; int written, err; *errorCodePtr = 0; dprintf("Write(%p, %d)", (void *) statePtr, toWrite); dprintBuffer(buf, toWrite); /* Abort if the user verify callback is still running to avoid triggering * another call before the current one is complete. */ if (statePtr->flags & TLS_TCL_CALLBACK) { dprintf("Don't process output while callbacks are running"); written = -1; *errorCodePtr = EAGAIN; return -1; } /* If not initialized, do connect */ /* Can also check SSL_is_init_finished(ssl) */ if (statePtr->flags & TLS_TCL_INIT) { int tlsConnect; dprintf("Calling Tls_WaitForConnect"); tlsConnect = Tls_WaitForConnect(statePtr, errorCodePtr, 1); if (tlsConnect < 0) { dprintf("Got an error waiting to connect (tlsConnect = %i, *errorCodePtr = %i)", tlsConnect, *errorCodePtr); written = -1; if (*errorCodePtr == ECONNRESET) { dprintf("Got connection reset"); /* Soft EOF */ *errorCodePtr = 0; written = 0; |
︙ | ︙ | |||
671 672 673 674 675 676 677 | /* Same as SSL_want, but also checks the error queue */ err = SSL_get_error(statePtr->ssl, written); backingError = ERR_get_error(); if (written <= 0) { /* The retry flag is set by the BIO_set_retry_* functions */ if (BIO_should_retry(statePtr->bio)) { | | > | > | 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 | /* Same as SSL_want, but also checks the error queue */ err = SSL_get_error(statePtr->ssl, written); backingError = ERR_get_error(); if (written <= 0) { /* The retry flag is set by the BIO_set_retry_* functions */ if (BIO_should_retry(statePtr->bio)) { dprintf("Write failed with code %d, bytes written=%d: should retry", err, written); } else { dprintf("Write failed with code %d, bytes written=%d: error condition", err, written); } /* These are the same as BIO_retry_type */ if (BIO_should_read(statePtr->bio)) { dprintf("BIO has insufficient data to read and return"); } if (BIO_should_write(statePtr->bio)) { |
︙ | ︙ | |||
703 704 705 706 707 708 709 | dprintf("SSL_ERROR_NONE"); if (written < 0) { written = 0; } break; case SSL_ERROR_SSL: | | > > | | > | > > | | 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 | dprintf("SSL_ERROR_NONE"); if (written < 0) { written = 0; } break; case SSL_ERROR_SSL: /* A non-recoverable, fatal error in the SSL library occurred, usually a protocol error */ dprintf("SSL error, indicating that the connection has been aborted"); if (backingError != 0) { Tls_Error(statePtr, ERR_reason_error_string(backingError)); } else if (SSL_get_verify_result(statePtr->ssl) != X509_V_OK) { Tls_Error(statePtr, X509_verify_cert_error_string(SSL_get_verify_result(statePtr->ssl))); } else { Tls_Error(statePtr, "Unknown SSL error"); } *errorCodePtr = ECONNABORTED; written = -1; break; case SSL_ERROR_WANT_READ: /* Operation did not complete due to not enough data was available. Retry again later. */ dprintf("Got SSL_ERROR_WANT_READ, mapping it to EAGAIN"); *errorCodePtr = EAGAIN; written = -1; statePtr->want |= TCL_READABLE; BIO_set_retry_read(statePtr->bio); break; case SSL_ERROR_WANT_WRITE: /* Operation did not complete due to unable to send all data to the BIO. Retry later. */ dprintf("Got SSL_ERROR_WANT_WRITE, mapping it to EAGAIN"); *errorCodePtr = EAGAIN; written = -1; statePtr->want |= TCL_WRITABLE; BIO_set_retry_write(statePtr->bio); break; case SSL_ERROR_WANT_X509_LOOKUP: /* Operation didn't complete since application callback set by SSL_CTX_set_client_cert_cb() asked to be called again. */ dprintf("Got SSL_ERROR_WANT_X509_LOOKUP, mapping it to EAGAIN"); *errorCodePtr = EAGAIN; written = -1; break; case SSL_ERROR_SYSCALL: /* Some non-recoverable, fatal I/O error occurred */ |
︙ | ︙ | |||
766 767 768 769 770 771 772 | *errorCodePtr = Tcl_GetErrno(); written = -1; Tls_Error(statePtr, ERR_reason_error_string(backingError)); } break; case SSL_ERROR_ZERO_RETURN: | | > | | > | 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 | *errorCodePtr = Tcl_GetErrno(); written = -1; Tls_Error(statePtr, ERR_reason_error_string(backingError)); } break; case SSL_ERROR_ZERO_RETURN: /* Peer has closed the connection by sending the close_notify alert. Can't read, but can write. Need to return an EOF, so channel is closed which will send an SSL_shutdown(). */ dprintf("Got SSL_ERROR_ZERO_RETURN, this means an EOF has been reached"); *errorCodePtr = 0; written = 0; Tls_Error(statePtr, "Peer has closed the connection for writing by sending the close_notify alert"); break; case SSL_ERROR_WANT_ASYNC: /* Used with flag SSL_MODE_ASYNC, op didn't complete because an async engine is still processing data */ dprintf("Got SSL_ERROR_WANT_ASYNC, mapping this to EAGAIN"); *errorCodePtr = EAGAIN; written = -1; break; default: dprintf("unknown error: %d", err); |
︙ | ︙ | |||
803 804 805 806 807 808 809 | * Get parent channel for a stacked channel. * * Results: * Tcl_Channel or NULL if none. * *----------------------------------------------------------------------------- */ | | > > > | 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 | * Get parent channel for a stacked channel. * * Results: * Tcl_Channel or NULL if none. * *----------------------------------------------------------------------------- */ Tcl_Channel Tls_GetParent( State *statePtr, /* Connection state info */ int maskFlags) /* Which flags to process */ { dprintf("Requested to get parent of channel %p", statePtr->self); if ((statePtr->flags & ~maskFlags) & TLS_TCL_FASTPATH) { dprintf("Asked to get the parent channel while we are using FastPath -- returning NULL"); return NULL; } return Tcl_GetStackedChannel(statePtr->self); |
︙ | ︙ | |||
830 831 832 833 834 835 836 | * * Side effects: * Updates channel option to new value. * *----------------------------------------------------------------------------- */ static int | | > | 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 | * * Side effects: * Updates channel option to new value. * *----------------------------------------------------------------------------- */ static int TlsSetOptionProc( ClientData instanceData, /* Socket state. */ Tcl_Interp *interp, /* For errors - can be NULL. */ const char *optionName, /* Name of the option to set the value for, or * NULL to get all options and their values. */ const char *optionValue) /* Value for option. */ { State *statePtr = (State *) instanceData; Tcl_Channel parent = Tls_GetParent(statePtr, TLS_TCL_FASTPATH); |
︙ | ︙ | |||
873 874 875 876 877 878 879 | * * Side effects: * None. * *------------------------------------------------------------------- */ static int | | > | | | > | 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 | * * Side effects: * None. * *------------------------------------------------------------------- */ static int TlsGetOptionProc( ClientData instanceData, /* Socket state. */ Tcl_Interp *interp, /* For errors - can be NULL. */ const char *optionName, /* Name of the option to retrieve the value for, * or NULL to get all options and their values. */ Tcl_DString *optionValue) /* Where to store the computed value initialized by caller. */ { State *statePtr = (State *) instanceData; Tcl_Channel parent = Tls_GetParent(statePtr, TLS_TCL_FASTPATH); Tcl_DriverGetOptionProc *getOptionProc; dprintf("Called"); /* Pass to parent */ getOptionProc = Tcl_ChannelGetOptionProc(Tcl_GetChannelType(parent)); if (getOptionProc != NULL) { return (*getOptionProc)(Tcl_GetChannelInstanceData(parent), interp, optionName, optionValue); } else if (optionName == (char*) NULL) { /* * Request is query for all options, this is ok. */ return TCL_OK; } /* |
︙ | ︙ | |||
918 919 920 921 922 923 924 | * None. * * Side effects: * Creates notification event. * *----------------------------------------------------------------------------- */ | | > > | 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 | * None. * * Side effects: * Creates notification event. * *----------------------------------------------------------------------------- */ static void TlsChannelHandlerTimer( ClientData clientData) /* Socket state. */ { State *statePtr = (State *) clientData; int mask = statePtr->want; /* Init to SSL_ERROR_WANT_READ and SSL_ERROR_WANT_WRITE */ dprintf("Called"); statePtr->timer = (Tcl_TimerToken) NULL; |
︙ | ︙ | |||
970 971 972 973 974 975 976 | * Side effects: * Sets up the time-based notifier so that future events on the channel * will be seen by TCL. * *----------------------------------------------------------------------------- */ static void | | > | | | | | | | < | | 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 | * Side effects: * Sets up the time-based notifier so that future events on the channel * will be seen by TCL. * *----------------------------------------------------------------------------- */ static void TlsWatchProc( ClientData instanceData, /* Connection state info */ int mask) /* Events of interest; an OR-ed combination of * TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION. */ { Tcl_Channel parent; State *statePtr = (State *) instanceData; Tcl_DriverWatchProc *watchProc; int pending = 0; dprintf("Called with mask 0x%02x", mask); dprintFlags(statePtr); /* Abort if the user verify callback is still running to avoid triggering * another call before the current one is complete. */ if (statePtr->flags & TLS_TCL_CALLBACK) { dprintf("Callback is on-going, doing nothing"); return; } parent = Tls_GetParent(statePtr, TLS_TCL_FASTPATH); if (statePtr->flags & TLS_TCL_HANDSHAKE_FAILED) { dprintf("Asked to watch a socket with a failed handshake -- nothing can happen here"); dprintf("Unregistering interest in the lower channel"); watchProc = Tcl_ChannelWatchProc(Tcl_GetChannelType(parent)); watchProc(Tcl_GetChannelInstanceData(parent), 0); statePtr->watchMask = 0; return; } statePtr->watchMask = mask; /* No channel handlers any more. We will be notified automatically about * events on the channel below via a call to our 'TransformNotifyProc'. But * we have to pass the interest down now. We are allowed to add additional * 'interest' to the mask if we want to, but this transformation has no * such interest. It just passes the request down, unchanged. */ dprintf("Registering our interest in the lower channel (chan=%p)", (void *) parent); watchProc = Tcl_ChannelWatchProc(Tcl_GetChannelType(parent)); watchProc(Tcl_GetChannelInstanceData(parent), mask); /* Do we have any pending events */ pending = (statePtr->want || \ |
︙ | ︙ | |||
1056 1057 1058 1059 1060 1061 1062 | * The appropriate Tcl_File handle or NULL if none. * * Side effects: * None. * *----------------------------------------------------------------------------- */ | | > | > | | | | > | | | 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 | * The appropriate Tcl_File handle or NULL if none. * * Side effects: * None. * *----------------------------------------------------------------------------- */ static int TlsGetHandleProc( ClientData instanceData, /* Socket state. */ int direction, /* TCL_READABLE or TCL_WRITABLE */ ClientData *handlePtr) /* Handle associated with the channel */ { State *statePtr = (State *) instanceData; return Tcl_GetChannelHandle(Tls_GetParent(statePtr, TLS_TCL_FASTPATH), direction, handlePtr); } /* *----------------------------------------------------------------------------- * * TlsNotifyProc -- * * This procedure is invoked by the generic IO level to notify the channel * that an event has occurred on the underlying channel. It is used by * stacked channel drivers that wish to be notified of events that occur * on the underlying (stacked) channel. * * Results: * Type of event or 0 if failed * * Side effects: * May process the incoming event by itself. * *----------------------------------------------------------------------------- */ static int TlsNotifyProc( ClientData instanceData, /* Socket state. */ int mask) /* type of event that occurred: OR-ed * combination of TCL_READABLE or TCL_WRITABLE */ { State *statePtr = (State *) instanceData; int errorCode = 0; dprintf("Called"); /* |
︙ | ︙ |
Modified generic/tlsInt.h
from [a9b308f767]
to [be5af53e3f].
︙ | ︙ | |||
161 162 163 164 165 166 167 | if (text != NULL) Tcl_ListObjAppendElement(interp, obj, Tcl_NewStringObj(text, -1)); \ Tcl_ListObjAppendElement(interp, obj, (tclObj != NULL) ? tclObj : Tcl_NewStringObj("", 0)); \ } /* * Defines for State.flags */ | | | > | | | | | | | | | | | | 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | if (text != NULL) Tcl_ListObjAppendElement(interp, obj, Tcl_NewStringObj(text, -1)); \ Tcl_ListObjAppendElement(interp, obj, (tclObj != NULL) ? tclObj : Tcl_NewStringObj("", 0)); \ } /* * Defines for State.flags */ #define TLS_TCL_ASYNC (1<<0) /* Non-blocking mode */ #define TLS_TCL_SERVER (1<<1) /* Server-Side */ #define TLS_TCL_INIT (1<<2) /* Initializing connection */ #define TLS_TCL_DEBUG (1<<3) /* Show debug tracing */ #define TLS_TCL_CALLBACK (1<<4) /* In a callback, prevent update * looping problem. [Bug 1652380] */ #define TLS_TCL_HANDSHAKE_FAILED (1<<5) /* Set on handshake failures and once set, all * further I/O will result in ECONNABORTED errors. */ #define TLS_TCL_FASTPATH (1<<6) /* The parent channel is being used * directly by the SSL library. */ #define TLS_TCL_DELAY (5) /* * This structure describes the per-instance state of an SSL channel. * * The SSL processing context is maintained here, in the ClientData */ typedef struct State { Tcl_Channel self; /* This socket channel */ Tcl_TimerToken timer; /* I/O timer handle */ int flags; /* See State.flags above */ int watchMask; /* Current WatchProc mask */ int want; /* Pending wants from OpenSSL */ int mode; /* Current mode of parent channel */ Tcl_Interp *interp; /* Interpreter in which this resides */ Tcl_Obj *callback; /* Script called for tracing, info, and errors */ Tcl_Obj *password; /* Script called for certificate password */ Tcl_Obj *vcmd; /* Script called to verify or validate protocol config */ int vflags; /* Verify flags */ SSL *ssl; /* Struct for SSL processing */ SSL_CTX *ctx; /* SSL Context */ BIO *bio; /* Struct for SSL processing */ BIO *p_bio; /* Parent BIO (that is layered on Tcl_Channel) */ unsigned int protos_len; /* Length of protos */ unsigned char *protos; /* List of supported protocols in protocol format */ |
︙ | ︙ |
Modified win/makefile.vc
from [ff59eea958]
to [368ba5e1ae].
︙ | ︙ | |||
36 37 38 39 40 41 42 43 44 45 46 47 48 49 | # Define any additional project include flags # SSL_INSTALL_FOLDER = with the OpenSSL installation folder following. PRJ_INCLUDES = -I"$(SSL_INSTALL_FOLDER)\include" -I"$(OPENSSL_INSTALL_DIR)\include" -I"$(TMP_DIR)" # Define any additional compiler flags that might be required for the project PRJ_DEFINES = -D NO_SSL2 -D NO_SSL3 /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_DEPRECATE /D__STDC_WANT_SECURE_LIB__=1 # /DTCLEXT_TCLTLS_DEBUG # # SSL Libs: # 1. ${LIBCRYPTO}.dll # 2. ${LIBSSL}.dll # Where LIBCRYPTO (#1.) and LIBSSL (#2.) are defined as follows: | > | 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | # Define any additional project include flags # SSL_INSTALL_FOLDER = with the OpenSSL installation folder following. PRJ_INCLUDES = -I"$(SSL_INSTALL_FOLDER)\include" -I"$(OPENSSL_INSTALL_DIR)\include" -I"$(TMP_DIR)" # Define any additional compiler flags that might be required for the project PRJ_DEFINES = -D NO_SSL2 -D NO_SSL3 /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_DEPRECATE /D__STDC_WANT_SECURE_LIB__=1 # /DTCLTLS_SSL_USE_FASTPATH # /DTCLEXT_TCLTLS_DEBUG # # SSL Libs: # 1. ${LIBCRYPTO}.dll # 2. ${LIBSSL}.dll # Where LIBCRYPTO (#1.) and LIBSSL (#2.) are defined as follows: |
︙ | ︙ | |||
84 85 86 87 88 89 90 | make-docs: !IF EXIST($(DTPLITE)) "$(TCLSH)" "$(DTPLITE)" -o "$DOCDIR" html "$(ROOT)\doc" "$(TCLSH)" "$(DTPLITE)" -o "$DOCDIR" nroff "$(ROOT)\doc" !ENDIF | | | 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | make-docs: !IF EXIST($(DTPLITE)) "$(TCLSH)" "$(DTPLITE)" -o "$DOCDIR" html "$(ROOT)\doc" "$(TCLSH)" "$(DTPLITE)" -o "$DOCDIR" nroff "$(ROOT)\doc" !ENDIF docs: make-docs-n make-docs-html all: setup default-target clean: default-clean realclean: default-hose |
︙ | ︙ |