<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">Summary of command line options</a></li>
<li class="doctools_subsection"><a href="#subsection2">When are command line options needed?</a></li>
<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="#subsection3">Values for Command Callback</a></li>
<li class="doctools_subsection"><a href="#subsection4">Values for Password Callback</a></li>
<li class="doctools_subsection"><a href="#subsection5">Values for Validate Command Callback</a></li>
<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>

<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.
The default is &quot;<b class="file">cert.pem</b>&quot;, 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>
<dd><p>Specifies the file with the Certificate Authority (CA) certificates to use in
<b class="const">PEM</b> file format. The default is &quot;<b class="file">cert.pem</b>&quot;, 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 Windows, set to &quot;<b class="const">org.openssl.winstore://</b>&quot;
to use the built-in 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>
Starting with OpenSSL 3.2 on MS Windows, set to &quot;<b class="const">org.openssl.winstore://</b>&quot;
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 in PEM format to use
<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 &quot;<b class="const">:</b>&quot; separated list of ciphers.
Ciphers can be combined using the &quot;<b class="const">+</b>&quot; character.

<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 value is to use the file
<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 peer during the SSL handshake. This is needed to do
Certificate Validation. Default is <b class="const">true</b>.
<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 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 is <b class="const">false</b> since not all platforms have
certificates to validate against in a form compatible with OpenSSL.
<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

<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">Summary of command line options</a></h3>
<p>The following options are used for peer Certificate Validation:</p>
<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 &quot;<b class="file">/etc/ssl/certs</b>&quot; 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 &quot;<b class="file">cert.pem</b>&quot;, in the OpenSSL directory. On
Linux/Unix systems, this is usually &quot;<b class="file">/etc/ssl/ca-bundle.pem</b>&quot;. The default file
can be overridden by the <b class="variable">SSL_CERT_FILE</b> environment variable.</p></dd>
<b class="const">PEM</b> file format. The default is &quot;<b class="file">cert.pem</b>&quot;, in the OpenSSL
directory. On Linux/Unix systems, this is usually &quot;<b class="file">/etc/ssl/ca-bundle.pem</b>&quot;.
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 Windows, set to &quot;<b class="const">org.openssl.winstore://</b>&quot;
to use the built-in Windows Certificate Store. This store only supports root
certificate stores.</p></dd>
Starting with OpenSSL 3.2 on MS Windows, set to &quot;<b class="const">org.openssl.winstore://</b>&quot;
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 peer during the SSL handshake. This is needed to do
Certificate Validation. 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>
<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 peer during the SSL handshake. If this is set
to <b class="const">true</b>, then <i class="arg">-request</i> must also be set to <b class="const">true</b> and either
<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
<i class="arg">-cadir</i>, <i class="arg">-cafile</i>, <i class="arg">-castore</i>, or a platform default must be
provided in order to validate against. The default is <b class="const">false</b> since not
all platforms have certificates to validate against in a form compatible with
<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>
OpenSSL. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for more details.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">When are command line options needed?</a></h3>
<p>By default, a client TLS connection does <em>NOT</em> validate the server certificate
chain. 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 Windows do not. In
order to use the <b class="option">-require</b> option, one of the following must be true:</p>
<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, if the CA
certificates 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>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 Windows and OpenSSL is installed, the <b class="variable">SSL_CERT_DIR</b> and/or
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 Windows, starting in OpenSSL 3.2, it is now possible to access the
built-in Windows Certificate Store from OpenSSL. This can be achieved by
<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 &quot;<b class="const">org.openssl.winstore://</b>&quot;.</p></li>
<li><p>If OpenSSL is not installed or the CA certificates are not available in PEM
<li><p>If OpenSSL is not installed, the CA certificates must be downloaded and
installed with the user software. The CURL team makes them available at
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 &quot;<b class="file">cacert.pem</b>&quot; 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="subsection3" class="doctools_subsection"><h3><a name="subsection3">Values for Command Callback</a></h3>
<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

<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="subsection4" class="doctools_subsection"><h3><a name="subsection4">Values for Password Callback</a></h3>
<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="subsection5" class="doctools_subsection"><h3><a name="subsection5">Values for Validate Command Callback</a></h3>
<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>

[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.
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.
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 Windows, set to "[const "org.openssl.winstore://"]"
to use the built-in Windows Certificate Store. This store only supports root
certificate stores. See [sectref "Certificate Validation"] for more details.
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 in PEM format to use
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.

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 value is to use the file
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 peer during the SSL handshake. This is needed to do
Certificate Validation. Default is [const true].
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 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 is [const false] since not all platforms have
certificates to validate against in a form compatible with OpenSSL.
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

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:
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.
[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 Windows, set to "[const "org.openssl.winstore://"]"
to use the built-in Windows Certificate Store. This store only supports root
certificate stores.
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 peer during the SSL handshake. This is needed to do
Certificate Validation. Default is [const true]. In addition, the
client can manually inspect and accept or reject each certificate using the
[arg -validatecommand] option.
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 peer during the SSL handshake. If this is set
to [const true], then [arg -request] must also be set to [const true] and either
[arg -cadir], [arg -cafile], [arg -castore], or a platform default must be
provided in order to validate against. The default is [const false] since not
all platforms have certificates to validate against in a form compatible with
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.
OpenSSL. See [sectref "Certificate Validation"] for more details.

[list_end]

[subsection "When are command line options needed?"]

By default, a client TLS connection does [emph NOT] validate the server certificate
chain. 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 Windows do not. In
order to use the [option -require] option, one of the following must be true:
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, if the CA
certificates 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.
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 Windows and OpenSSL is installed, the [var SSL_CERT_DIR] and/or
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 Windows, starting in OpenSSL 3.2, it is now possible to access the
built-in Windows Certificate Store from OpenSSL. This can be achieved by
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
If OpenSSL is not installed, the CA certificates must be downloaded and
installed with the user software. The CURL team makes them available at
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]

\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\&.
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\&.
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 Windows, set to "\fBorg\&.openssl\&.winstore://\fR"
to use the built-in Windows Certificate Store\&. This store only supports root
certificate stores\&. See \fBCertificate Validation\fR for more details\&.
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 in PEM format to use
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\&.

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 value is to use the file
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 peer during the SSL handshake\&. This is needed to do
Certificate Validation\&. Default is \fBtrue\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 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 is \fBfalse\fR since not all platforms have
certificates to validate against in a form compatible with OpenSSL\&.
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

\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:
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\&.
\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 Windows, set to "\fBorg\&.openssl\&.winstore://\fR"
to use the built-in Windows Certificate Store\&. This store only supports root
certificate stores\&.
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 peer during the SSL handshake\&. This is needed to do
Certificate Validation\&. Default is \fBtrue\fR\&. In addition, the
client can manually inspect and accept or reject each certificate using the
\fI-validatecommand\fR option\&.
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 peer during the SSL handshake\&. If this is set
to \fBtrue\fR, then \fI-request\fR must also be set to \fBtrue\fR and either
\fI-cadir\fR, \fI-cafile\fR, \fI-castore\fR, or a platform default must be
provided in order to validate against\&. The default is \fBfalse\fR since not
all platforms have certificates to validate against in a form compatible with
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\&.
OpenSSL\&. See \fBCertificate Validation\fR for more details\&.
.PP
.SS "WHEN ARE COMMAND LINE OPTIONS NEEDED?"
By default, a client TLS connection does \fINOT\fR validate the server certificate
chain\&. 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 Windows do not\&. In
order to use the \fB-require\fR option, one of the following must be true:
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, if the CA
certificates 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\&.
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 Windows and OpenSSL is installed, the \fBSSL_CERT_DIR\fR and/or
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 Windows, starting in OpenSSL 3\&.2, it is now possible to access the
built-in Windows Certificate Store from OpenSSL\&. This can be achieved by
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
If OpenSSL is not installed, the CA certificates must be downloaded and
installed with the user software\&. The CURL team makes them available at
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"

	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_all(%p)", statePtr->bio);
	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)", 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");
}


/*
 * 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 <-- BioWrite| SSL |BIO_write <-- TlsOutputProc <-- Write|      |
  |socket|      <encrypted>        | BIO |            <unencrypted>            | App  |
  |      |Tcl_ReadRaw  -->  BioRead|     |BIO_Read  --> TlsInputProc  -->  Read|      |
  +------+                         +-----+                                     +------+
 +------+                        +---+                                 +---+
 |      |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;

    return res;
}

/*
 *-----------------------------------------------------------------------------
 *
 * BioWrite --
 * 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 BioWrite(BIO *bio, const char *buf, int bufLen) {
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] BioWrite(bio=%p, buf=%p, len=%d)", (void *)chan, (void *) bio, buf, bufLen);
    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] BioWrite(%d) -> %" TCL_SIZE_MODIFIER "d [tclEof=%d; tclErrno=%d: %s]",
    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) {

	    BIO_set_retry_write(bio);

	} else {
	    dprintf("Unexpected error: %i=%s", tclErrno, Tcl_ErrnoMsg(tclErrno));
	}
    }

    dprintf("BioWrite returning %" TCL_SIZE_MODIFIER "d", ret);
    dprintf("BioOutput returning %" TCL_SIZE_MODIFIER "d", ret);
    return (int) ret;
}

/*
 *-----------------------------------------------------------------------------
 *
 * BioRead --
 * 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

 * 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 BioRead(BIO *bio, char *buf, int bufLen) {
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] BioRead(bio=%p, buf=%p, len=%d)", (void *) chan, (void *) bio, buf, bufLen);
    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] BioRead(%d) -> %" TCL_SIZE_MODIFIER "d [tclEof=%d; blocked=%d; tclErrno=%d: %s]",
    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) {

	    BIO_set_retry_read(bio);

	} else {
	    dprintf("Unexpected error: %i=%s", tclErrno, Tcl_ErrnoMsg(tclErrno));
	}
    }

    dprintf("BioRead returning %" TCL_SIZE_MODIFIER "d", ret);
    dprintf("BioInput returning %" TCL_SIZE_MODIFIER "d", ret);
    return (int) ret;
}

/*
 *-----------------------------------------------------------------------------
 *
 * BioPuts --

 *
 *-----------------------------------------------------------------------------
 */

static int BioPuts(BIO *bio, const char *str) {
    dprintf("BioPuts(%p) \"%s\"", bio, str);

    return BioWrite(bio, str, (int) strlen(str));
    return BioOutput(bio, str, (int) strlen(str));
}

/*
 *-----------------------------------------------------------------------------
 *
 * BioCtrl --
 *

		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 = BioWrite(bio, NULL, 0);*/
		/*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:

	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, BioWrite);
	BIO_meth_set_write(BioMethods, BioOutput);
	/* Not used BIO_meth_set_read_ex */
	BIO_meth_set_read(BioMethods, BioRead);
	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.
     * 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);
	tclGetChannelHandleRet = Tcl_GetChannelHandle(parentChannel,
	    TCL_READABLE, &parentChannelFdIn_p);
	if (tclGetChannelHandleRet == TCL_OK) {
	    tclGetChannelHandleRet = Tcl_GetChannelHandle(parentChannel, TCL_WRITABLE, &parentChannelFdOut_p);
	    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);
	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;
    }

 *	tclSSL (Colin McCormack, Shared Technology)
 *	SSLtcl (Peter Antman)
 *
 */

/*
		tlsBIO.c				tlsIO.c
  +------+                         +-----+                                     +------+
  |      |Tcl_WriteRaw <-- BioWrite| SSL |BIO_write <-- TlsOutputProc <-- Write|      |
  |socket|      <encrypted>        | BIO |            <unencrypted>            | App  |
  |      |Tcl_ReadRaw  -->  BioRead|     |BIO_Read  --> TlsInputProc  -->  Read|      |
  +------+                         +-----+                                     +------+
 +------+                        +---+                                 +---+
 |      |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>

/*
 *-----------------------------------------------------------------------------

 *	0 if successful or POSIX error code if failed.
 *
 * Side effects:
 *	Sets the device into blocking or nonblocking mode.
 *
 *-----------------------------------------------------------------------------
 */
static int TlsBlockModeProc(ClientData instanceData, int 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
 *	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.
 *	used.
 *
 * Results:
 *	0 if successful or POSIX error code if failed.
 *
 * Side effects:
 *	Closes the socket of the channel.
 *
 *-----------------------------------------------------------------------------
 */
static int TlsCloseProc(ClientData instanceData, Tcl_Interp *interp) {
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. */
    /* 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. */
    /* 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,    /* The socket state. */
    Tcl_Interp *interp,		/* For errors - can be NULL. */
    int flags)			/* Flags to close read and/or 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);

 *    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, int *errorCodePtr, int handshakeFailureIsPermanent) {
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);

	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 */
	    /* 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,
		Tls_Error(statePtr, X509_verify_cert_error_string(SSL_get_verify_result(statePtr->ssl)));
		    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;

		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(). */
	    /* 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.  */
	    /* 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_ZERO_RETURN, 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. */
	    /* 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;

	    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:
	    /* App 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. */
	    /* 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 */
	    /* 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. */
	    /* 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. */
	    /* 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). */
	    /* 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;

 *
 * 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, char *buf, int bufSize, int *errorCodePtr) {
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);

    /* Skip if user verify callback is still running */
    /* 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) */

	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 */
	    /* 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,
		Tls_Error(statePtr, X509_verify_cert_error_string(SSL_get_verify_result(statePtr->ssl)));
		    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:
	    /* Op did not complete due to not enough data was available. Retry later. */
	    /* 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:
	    /* Op did not complete due to unable to send all data to the BIO. Retry later. */
	    /* 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
	    /* Op didn't complete since callback set by SSL_CTX_set_client_cert_cb() asked to be called again */
	       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());
		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(). */
	    /* 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, op didn't complete because an async engine is still processing data */
	    /* 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);

 *	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, const char *buf, int toWrite, int *errorCodePtr) {
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);

    /* Skip if user verify callback is still running */
    /* 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);
	    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;

    /* 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);
	    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);
	    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)) {

	    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 */
	    /* 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,
		Tls_Error(statePtr, X509_verify_cert_error_string(SSL_get_verify_result(statePtr->ssl)));
		    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:
	    /* Op did not complete due to not enough data was available. Retry later. */
	    /* 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:
	    /* Op did not complete due to unable to send all data to the BIO. Retry later. */
	    /* 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
	    /* Op didn't complete since callback set by SSL_CTX_set_client_cert_cb() asked to be called again */
	       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 */

		*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(). */
	    /* 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 */
	    /* 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);

 *	Get parent channel for a stacked channel.
 *
 * Results:
 *	Tcl_Channel or NULL if none.
 *
 *-----------------------------------------------------------------------------
 */
Tcl_Channel Tls_GetParent(State *statePtr, int maskFlags) {
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);

 *
 * Side effects:
 *	Updates channel option to new value.
 *
 *-----------------------------------------------------------------------------
 */
static int
TlsSetOptionProc(ClientData instanceData,    /* Socket state. */
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);

 *
 * Side effects:
 *	None.
 *
 *-------------------------------------------------------------------
 */
static int
TlsGetOptionProc(ClientData instanceData,    /* Socket state. */
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. */
    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);
	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;
    }
    /*

 *	None.
 *
 * Side effects:
 *	Creates notification event.
 *
 *-----------------------------------------------------------------------------
 */
static void TlsChannelHandlerTimer(ClientData clientData) {
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;

 * 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,    /* The socket state. */
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("TlsWatchProc(0x%x)", mask);
    dprintf("Called with mask 0x%02x", mask);
    dprintFlags(statePtr);

    /* Pretend to be dead as long as the verify callback is running.
     * Otherwise that callback could be invoked recursively. */
    /* 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
    /* 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
     * to. But this transformation has no such interest. It just passes
     * the request down, unchanged.
     * 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 || \

 *	The appropriate Tcl_File handle or NULL if none.
 *
 * Side effects:
 *	None.
 *
 *-----------------------------------------------------------------------------
 */
static int TlsGetHandleProc(ClientData instanceData,    /* Socket state. */
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);
    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.
 *	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 */
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");

    /*

    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_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_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;
	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 */
	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 */
	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 */
	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 */

# 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:

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 
docs: make-docs-n make-docs-html

all: setup default-target

clean: default-clean

realclean: default-hose