This extension is compatible with OpenSSL 1.1.1 or later. It requires Tcl +version 8.5 or later and will work with Tcl 9.0.
+The following are the commands provided by the TcLTLS package. See the -Examples for example usage and the "demos" directory for +Examples for example usage and the "demos" directory for more example usage.
Optional function to set the default options used by tls::socket. If you call tls::import directly, the values set by this command have no effect. @@ -201,22 +206,22 @@ quic. This option is new for TclTLS 1.8.
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 SSL_CERT_DIR environment -variable. See Certificate Validation for more details.
Specifies the file with the Certificate Authority (CA) certificates to use in PEM file format. The default is "cert.pem", in the OpenSSL directory. The default file can be overridden by the SSL_CERT_FILE environment -variable. See Certificate Validation for more details.
Specifies the Uniform Resource Identifier (URI) for the Certificate Authority (CA) store, which may be a single container or a catalog of containers. Starting with OpenSSL 3.2 on MS Windows, set to "org.openssl.winstore://" to use the built-in MS Windows Certificate Store. -See Certificate Validation for more details. +See Certificate Validation for more details. This option is new for TclTLS 1.8.
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.
Specifies the callback command to be invoked at several points during the handshake to pass errors, tracing information, and protocol messages. -See Callback Options for more info.
Specifies the Diffie-Hellman (DH) parameters file.
Specifies the private key file. The default is to use the file specified by the -certfile option.
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. This option has changed for -TclTLS 1.8. See Callback Options for more info.
Allow post-handshake session ticket updates. This option is new for TclTLS 1.8.
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 true. Starting in TclTLS 2.0, If set to false and -require is true, then this will be overridden to true. -See Certificate Validation for more details.
Require a valid certificate from the peer during the SSL handshake. If this is set to true, then -request must also be set to true and a either -cadir, -cafile, -castore, or a platform default must be provided in order to validate against. The default in TclTLS 1.8 and earlier versions is false since not all platforms have certificates to validate against in a form compatible with OpenSSL. Starting in TclTLS 2.0, the default is true. -See Certificate Validation for more details.
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 @@ -317,11 +322,11 @@
Specifies the callback command to invoke to validate the peer certificates and other config info during the protocol negotiation phase. This can be used by TCL scripts to perform their own Certificate Validation to supplement the default validation provided by OpenSSL. The script must return a boolean true -to continue the negotiation. See Callback Options for more info. +to continue the negotiation. See Callback Options for more info. This option is new for TclTLS 1.8.
Compliment to tls::import. Used to remove the top level stacked channel from channel. This unstacks the encryption of a regular TCL channel. An @@ -538,11 +543,11 @@ This command is new for TclTLS 1.8.
Returns the OpenSSL version string.
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 @@ -587,11 +592,11 @@ (CA) store, which may be a single container or a catalog of containers. Starting with OpenSSL 3.2 on MS Windows, set to "org.openssl.winstore://" to use the built-in MS Windows Certificate Store. Starting in TclTLS 2.0, this is the default if -cadir, -cadir, and -castore are not specified. This store only supports root certificate stores. See -Certificate Validation for more details.
+Certificate Validation for more details.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 true. Starting in TclTLS 2.0, If set to false and -require is true, then this will be overridden to true. @@ -640,11 +645,11 @@ -cadir or -cafile options to the CA cert file's install location. It is your responsibility to keep this file up to date.
As previously described, each channel can be given their own callbacks to handle intermediate processing by the OpenSSL library, using the -command, -password, and -validate_command options passed to either of tls::socket or tls::import. Unlike previous versions of TclTLS, only if the callback generates an error, @@ -798,11 +803,11 @@ implementations.
The use of the reference callbacks tls::callback, tls::password, and tls::validate_command is not recommended. They may be removed from future releases.
For most debugging needs, the -callback option can be used to provide sufficient insight and information on the TLS handshake and progress. If further troubleshooting insight is needed, the compile time option --enable-debug can be used to get detailed execution flow status.
TLS key logging can be enabled by setting the environment variable @@ -817,13 +822,13 @@ certificate, even if it is invalid when the -validatecommand option is set to tls::validate_command.
The use of the variable tls::debug is not recommended. It may be removed from future releases.
The following are example scripts to download a webpage and file using the -http package. See Certificate Validation for when the +http package. See Certificate Validation for when the -cadir, -cafile, and -castore options are also needed. See the "demos" directory for more example scripts.
Example #1: Download a web page
package require http @@ -861,11 +866,11 @@ # Cleanup close $ch ::http::cleanup $token
The capabilities of this package can vary enormously based upon how the linked to OpenSSL library was configured and built. New versions may obsolete older protocol versions, add or remove ciphers, change default values, etc. Use the tls::protocols commands to obtain the supported protocol versions.
Index: doc/tls.man ================================================================== --- doc/tls.man +++ doc/tls.man @@ -22,10 +22,14 @@ [syscmd Tcl_StackChannel] API in TCL 8.4 and higher. These sockets behave exactly the same as channels created using the built-in [syscmd socket] command, but provide additional options for controlling the SSL/TLS session. +[section Compatibility] +This extension is compatible with OpenSSL 1.1.1 or later. It requires Tcl +version 8.5 or later and will work with Tcl 9.0. + [section Commands] The following are the commands provided by the TcLTLS package. See the [sectref Examples] for example usage and the [file demos] directory for more example usage. Index: doc/tls.n ================================================================== --- doc/tls.n +++ doc/tls.n @@ -309,10 +309,13 @@ binding to \fIOpenSSL\fR [https://www\&.openssl\&.org/], utilizing the \fBTcl_StackChannel\fR API in TCL 8\&.4 and higher\&. These sockets behave exactly the same as channels created using the built-in \fBsocket\fR command, but provide additional options for controlling the SSL/TLS session\&. +.SH COMPATIBILITY +This extension is compatible with OpenSSL 1\&.1\&.1 or later\&. It requires Tcl +version 8\&.5 or later and will work with Tcl 9\&.0\&. .SH COMMANDS The following are the commands provided by the TcLTLS package\&. See the \fBExamples\fR for example usage and the "\fIdemos\fR" directory for more example usage\&. .TP