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