TLS (SSL) TCL Commands

TCL Tls Extension Documentation

NAME

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

SYNOPSIS

package require Tcl ?8.5-?; package require tls ?1.8-?
: tls::init ?options?; tls::socket ?options? host port; tls::socket ?-server command? ?options? port; tls::handshake channel; tls::status ?-local? channel; tls::connection channel; tls::import channel ?options?; tls::unimport channel
: tls::ciphers ?protocol? ?verbose? ?supported?; tls::protocols; tls::version

COMMANDS

CERTIFICATE VALIDATION

CALLBACK OPTIONS

DEBUG

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

NAME

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

SYNOPSIS

package require Tcl ?8.5-?
package require tls ?1.8-?

tls::init ?options?
tls::socket ?options? host port
tls::socket ?-server command? ?options? port
tls::status ?-local? channel
tls::connection channel
tls::handshake channel
tls::import channel ?options?
tls::unimport channel

tls::ciphers ?protocol? ?verbose? ?supported?
tls::protocols
tls::version

This extension provides TCL script access to secure socket communications using the Transport Layer Security (TLS) protocol. It provides a generic binding to OpenSSL, utilizing the 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

Typically one would use the tls::socket command which provides compatibility with the native TCL socket command. In such cases tls::import should not be used directly.

tls::init ?options?: Optional function to set the default options used by tls::socket. If you call tls::import directly, this command has no effect. This command supports all of the same options as the tls::socket command, though you should limit your options to only TLS related ones.

tls::socket ?options? host port
tls::socket ?-server command? ?options? port: This is a helper function that utilizes the underlying commands (socket and tls::import) to create the connection. It behaves the same as the native TCL socket command, but also supports the tls:import command options and one additional option:
tls::import channel ?options?: Add SSL/TLS encryption to a regular TCL channel. It need not be a socket, but must provide bi-directional flow. Also set session parameters for SSL handshake.
tls::unimport channel: Provided for symmetry to tls::import, this unstacks the encryption of a regular TCL channel. An error is thrown if TLS is not the top stacked channel type.

tls::handshake channel: Forces handshake to take place, and returns 0 if handshake is still in progress (non-blocking), or 1 if the handshake was successful. If the handshake failed this routine will throw an error.

tls::status ?-local? channel: Returns the current status of an SSL channel. The result is a list of key-value pairs describing the SSL, certificate, and certificate verification status. If the SSL handshake has not yet completed, an empty list is returned. If -local is specified, then the local certificate is used.
tls::connection channel: Returns the current connection status of an SSL channel. The result is a list of key-value pairs describing the connection.
tls::ciphers ?protocol? ?verbose? ?supported?: Without any args, returns a list of all symmetric ciphers for use with the -cipher option. With protocol, only the ciphers supported for that protocol are returned. See tls::protocols command for the supported protocols. If verbose is specified as true then a verbose, human readable list is returned with additional information on the cipher. If supported is specified as true, then only the ciphers supported for protocol will be listed.

tls::protocols: Returns a list of the supported SSL/TLS protocols. Valid values are: ssl2, ssl3, tls1, tls1.1, tls1.2, and tls1.3. Exact list depends on OpenSSL version and compile time flags.

tls::version: Returns the OpenSSL version string.

CERTIFICATE VALIDATION

Summary of command line options:

The following options are used for certificate validation:

The -cadir option specifies the directory where the Certificate Authority (CA) certificates are stored. The default is platform specific, but is usually "/etc/ssl/certs" on Linux/Unix systems. The default location can be overridden via the SSL_CERT_DIR environment variable.
The -cafile option specifies the file that contains all of the Certificate Authority (CA) certificates in the PEM file format. The default is cert.pem, in the OpenSSL directory. On Linux/Unix systems, this is usually "/etc/ssl/ca-bundle.pem". The default file can be overridden via the SSL_CERT_FILE environment variable.
The -castore option contains the URI to the Certificate Authority (CA) store, which may be a single container or a catalog of containers. Starting with OpenSSL 3.2 on Windows, set this to "org.openssl.winstore://" to use the built-in Windows Certificate Store. The Windows cert store only supports root certificate stores.
The -request option is used to request the server send its certificate chain as part of the connection negotiation process. This is needed to do certificate validation. The default is true. In addition, the client can manually inspect and accept or reject each certificate using the -validatecommand option.
The -require option is used to require certificate validation be performed as part of the connection negotiation process. A valid CA directory, file, or store must be present for this to work.

When are command line options needed:

By default, a client TLS connection does 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 -require option, one of the following must be true:

On Linux and Unix systems with OpenSSL already installed, if the CA certificates are stored in the standard locations, or the SSL_CERT_DIR or SSL_CERT_FILE env vars are set, then no other options are needed.
If OpenSSL is not installed in the default location, or when using Mac OS or Windows and OpenSSL is installed, the SSL_CERT_DIR and/or SSL_CERT_FILE env vars or the -cadir and/or -cafile options must be defined.
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 setting the -castore option to "org.openssl.winstore://".
If OpenSSL is not installed, the CA certificates must be downloaded and installed with the user software. The CURL team makes them available at CA certificates extracted from Mozilla in the cacert.pem file. You must then either set the SSL_CERT_DIR and/or SSL_CERT_FILE env vars or the -cadir or -cafile options must be set to the file's install location. It is your responsibility to keep this file up to date.

CALLBACK OPTIONS

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

Invokes the specified callback script at several points during the OpenSSL handshake and use. See below for the possible arguments passed to the callback script. Values returned from the callback are ignored.

error channelId message

This form of callback is invoked whenever an error occurs during the initial connection, handshake, or I/O operations. The message argument can be from the Tcl_ErrnoMsg, OpenSSL function ERR_reason_error_string(), or a custom message.

info channelId major minor message type

This form of callback is invoked by the OpenSSL function SSL_set_info_callback() during the initial connection and handshake operations. The type argument is new for TLS 1.8. The arguments are:

Possible values for major are: handshake, alert, connect, accept.
Possible values for minor are: start, done, read, write, loop, exit.
The message argument is a descriptive string which may be generated either by SSL_state_string_long() or by SSL_alert_desc_string_long(), depending on the context.
For alerts, the possible values for type are: warning, fatal, and unknown. For others, info is used.

message channelId direction version content_type message

This form of callback is invoked by the OpenSSL function SSL_set_msg_callback() whenever a message is sent or received during the initial connection, handshake, or I/O operations. It is only available when OpenSSL is complied with the enable-ssl-trace option. Arguments are: direction is Sent or Received, version is the protocol version, content_type is the message content type, and message is more info from the SSL_trace API. This callback is new for TLS 1.8.

session channelId session_id ticket lifetime

This form of callback is invoked by the OpenSSL function SSL_CTX_sess_set_new_cb() whenever a new session id is sent by the server during the initial connection and handshake, but can also be received later if the -post_handshake option is used. Arguments are: session_id is the current session identifier, ticket is the session ticket info, and lifetime is the the ticket lifetime in seconds. This callback is new for TLS 1.8.

-password callback

Invokes the specified callback script when OpenSSL needs to obtain a password. See below for the possible arguments passed to the callback script. See below for valid return values.

password rwflag size: Invoked when loading or storing a PEM certificate with encryption. Where rwflag is 0 for reading/decryption or 1 for writing/encryption (can prompt user to confirm) and size is the max password length in bytes. The callback should return the password as a string. Both arguments are new for TLS 1.8.

-validatecommand callback

Invokes the specified callback script during handshake in order to validate the provided value(s). See below for the possible arguments passed to the callback script. If not specified, OpenSSL will accept 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.

alpn channelId protocol match

For servers, this form of callback is invoked when the client ALPN extension is received. If match is true, protocol is the first -alpn option specified protocol common to both the client and server. If not, the first client specified protocol is used. It is called after the hello and ALPN callbacks. This callback is new for TLS 1.8.

hello channelId servername

For servers, this form of callback is invoked during client hello message processing. The purpose is so the server can select the appropriate certificate to present to the client, and to make other configuration adjustments relevant to that server name and its configuration. It is called before the SNI and ALPN callbacks. This callback is new for TLS 1.8.

sni channelId servername

For servers, this form of callback is invoked when the Server Name Indication (SNI) extension is received. The servername argument is the client provided server name in the -servername option. The purpose is so when a server supports multiple names, the right certificate can be used. It is called after the hello callback but before the ALPN callback. This callback is new for TLS 1.8.

verify channelId depth cert status error

This form of callback is invoked by OpenSSL when a new certificate is received from the peer. It allows the client to check the certificate verification results and choose whether to continue or not. It is called for each certificate in the certificate chain.

The depth argument is the integer depth of the certificate in the certificate chain, where 0 is the peer certificate and higher values going up to the Certificate Authority (CA).
The cert argument is a list of key-value pairs similar to those returned by tls::status.
The status argument is the boolean validity of the current certificate where 0 is invalid and 1 is valid.
The error argument is the error message, if any, generated by X509_STORE_CTX_get_error().

Reference implementations of these callbacks are provided in the distribution as tls::callback, tls::password, and tls::validate_command respectively. Note that these are sample implementations only. In a more realistic deployment you would specify your own callback scripts on each TLS channel using the -command, -password, and -validate_command options.

The default behavior when the -command and -validate_command options are not specified is for TLS to process the associated library callbacks internally. The default behavior when the -password option is not specified is for TLS to process the associated library callbacks by attempting to call tls::password. The difference between these two behaviors is a consequence of maintaining compatibility with earlier 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.

DEBUG

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

Debug Examples

These examples use the default Unix platform SSL certificates. For standard installations, -cadir and -cafile should not be needed. If your certificates are in non-standard locations, update -cadir or use -cafile as needed.

Example #1: Use HTTP package


package require http
package require tls
set url "https://www.tcl.tk/"

http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs \
    -command ::tls::callback -password ::tls::password -validatecommand ::tls::validate_command]

# Check for error
set token [http::geturl $url]
if {[http::status $token] ne "ok"} {
    puts [format "Error %s" [http::status $token]]
}

# Get web page
set data [http::data $token]
puts [string length $data]

# Cleanup
::http::cleanup $token

Example #2: Use raw socket


package require tls

set url "www.tcl-lang.org"
set port 443

set ch [tls::socket -autoservername 1 -servername $url -request 1 -require 1 \
    -alpn {http/1.1} -cadir /etc/ssl/certs -command ::tls::callback \
    -password ::tls::password -validatecommand ::tls::validate_command $url $port]
chan configure $ch -buffersize 65536
tls::handshake $ch

puts $ch "GET / HTTP/1.1"
flush $ch
after 500
set data [read $ch]

array set status [tls::status $ch]
array set conn [tls::connection $ch]
array set chan [chan configure $ch]
close $ch
parray status
parray conn
parray chan

HTTPS EXAMPLE

Example #1: Get web page


package require http
package require tls
set url "https://www.tcl.tk/"

http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs]

# Check for error
set token [http::geturl $url]
if {[http::status $token] ne "ok"} {
    puts [format "Error %s" [http::status $token]]
}

# Get web page
set data [http::data $token]
puts $data

# Cleanup
::http::cleanup $token

Example #2: Download file


package require http
package require tls

set url "https://wiki.tcl-lang.org/sitemap.xml"
set filename [file tail $url]

http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs]

# Get file
set ch [open $filename wb]
set token [::http::geturl $url -blocksize 65536 -channel $ch]

# Cleanup
close $ch
::http::cleanup $token

SPECIAL CONSIDERATIONS

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.

TCL Tls Extension Documentation

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

CERTIFICATE VALIDATION

Summary of command line options:

When are command line options needed:

CALLBACK OPTIONS

DEBUG

Debug Examples

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

SEE ALSO