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