Index: README.txt ================================================================== --- README.txt +++ README.txt @@ -96,10 +96,19 @@ ------- If installing with MinGW, use the TEA build process. If using MS Visual C (MSVC), see the win/README.txt file for the installation instructions. + +Other +----- + +If OpenSSL is not installed on the system, the Certificate Authority (CA) +provided certificates must be downloaded and installed with the software. +The CURL team makes them available at https://curl.se/docs/caextract.html. +Look for the cacert.pem file. + Copyrights ========== Original TLS Copyright (C) 1997-2000 Matt Newman Index: doc/tls.html ================================================================== --- doc/tls.html +++ doc/tls.html @@ -35,22 +35,26 @@
tls::ciphers ?protocol? ?verbose? ?supported?
tls::protocols
tls::version
COMMANDS
+
CERTIFICATE VALIDATION
CALLBACK OPTIONS
+
DEBUG
HTTPS EXAMPLE
-
SPECIAL CONSIDERATIONS
+
SPECIAL CONSIDERATIONS
SEE ALSO
+

NAME

tls - binding to OpenSSL library for encrypted socket and I/O channel communications.

+

SYNOPSIS

@@ -68,10 +72,11 @@
tls::ciphers ?protocol? ?verbose? ?supported?
tls::protocols
tls::version

+

DESCRIPTION

@@ -81,10 +86,11 @@ Tcl_StackChannel API in TCL 8.4 and higher. These sockets behave exactly the same as channels created using the built-in socket command, along with additional options for controlling the SSL/TLS session.

+

COMMANDS

@@ -125,21 +131,26 @@ Protocol Negotiation (ALPN). For example: h2 and http/1.1, but not h3 or quic.
-cadir dir
Specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific and can be - set at compile time. This can be overridden via the SSL_CERT_DIR - environment variable.
+ set at compile time. The default location can be overridden via the + SSL_CERT_DIR environment variable. + See CERTIFICATE VALIDATION.
-cafile filename
Specifies the file with the Certificate Authority (CA) certificates - to use. The default is cert.pem, in the OpenSSL directory. This can - also be overridden via the SSL_CERT_FILE environment variable.
+ to use. The default is cert.pem, in the OpenSSL directory. + The default file can be overridden via the SSL_CERT_FILE + environment variable. + See CERTIFICATE VALIDATION.
-castore URI
-
URI for a store, which may be a single container or a catalog of - containers. On Windows, set to "org.openssl.winstore://" to use the - built-in Windows Cert Store. The Windows cert store only supports - root certificate stores.
+
URI for a Certificate Authority (CA) store, which may be a single + container or a catalog of containers. Starting with OpenSSL 3.2 on + Windows, set to "org.openssl.winstore://" to use the built-in + Windows Cert Store. The Windows cert store only supports root + certificate stores. + See CERTIFICATE VALIDATION.
-certfile filename
Specifies the file with the certificate to use in PEM format. This also contains the public key.
-cert binary_string
Specifies the certificate to use as a DER encoded string (X.509 DER).
@@ -176,16 +187,18 @@ See CALLBACK OPTIONS for more info.
-post_handshake bool
Allow post-handshake session ticket updates.
-request bool
Request a certificate from peer during the SSL handshake. This is - needed to do certificate validation. (default is true)
+ needed to do certificate validation. (default is true). + See CERTIFICATE VALIDATION.
-require bool
Require a valid certificate from peer during SSL handshake. If this - is set to true, then -request must also be set to true - and a either a -cadir, -cafile, or platform default must be provided in - order to validate against. (default is false)
+ is set to true, then -request must also be set to + true and a either a -cadir, -cafile, -castore, or platform default + must be provided in order to validate against. (default is false). + See CERTIFICATE VALIDATION.
-security_level integer
Specifies the security level (value from 0 to 5). The security level affects the 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 @@ -434,10 +447,46 @@ compile time flags.
 
tls::version
Returns the OpenSSL version string.
+
+ +
+ +

CERTIFICATE VALIDATION

+ +

+By default, a client TLS connection is set to NOT request nor validate the +server certificates. 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 -require option, one of the following must be true:

+ +

CALLBACK OPTIONS

@@ -445,12 +494,12 @@ As indicated above, individual channels 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. -If the callback generates an error, the bgerror command will be -invoked with the error information. +Unlike previous versions of TCL TLS, only if the callback generates an error, +will the bgerror command will be invoked with the error information.

-command callback
@@ -644,34 +693,36 @@ The use of the reference callbacks tls::callback, tls::password, and tls::validate_command is not recommended. They may be removed from future releases.

+

DEBUG

-TLS key logging can be enabled by setting the environment variable +

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 SSLKEYLOGFILE to the name of the file to log to. Then whenever TLS key material is generated or received it will be logged to the file. This is useful for logging key data for network logging tools to use to -decrypt the data. -

-The tls::debug variable provides some additional +decrypt the data.

+ +

The tls::debug variable provides some additional control over these reference callbacks. Its value is zero by default. Higher values produce more diagnostic output, and will also force the verify method in tls::callback to accept the certificate, even when it is invalid if the tls::validate_command -callback is used for the -validatecommand option. -

-

- -The use of the variable tls::debug is not recommended. -It may be removed from future releases. - -

+callback is used for the -validatecommand option.

+ +

The use of the variable tls::debug is not recommended. +It may be removed from future releases.

Debug Examples

These examples use the default Unix platform SSL certificates. For standard installations, -cadir and -cafile should not be needed. If your certificates @@ -725,10 +776,11 @@ close $ch parray status parray conn parray chan +

HTTPS EXAMPLE

@@ -774,10 +826,11 @@ # Cleanup close $ch ::http::cleanup $token +

SPECIAL CONSIDERATIONS