TLS (SSL) Tcl Commands

Tcl Tls Extension Documentation

NAME

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

SYNOPSIS

package require Tcl ?8.5?; package require tls
: 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::protocols; tls::version

COMMANDS

CALLBACK OPTIONS

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

NAME

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

SYNOPSIS

package require Tcl ?8.5?
package require tls

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::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 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 routine has no effect. Any of the options that tls::socket accepts can be set using this 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 (tls::import). It behaves exactly the same as the native Tcl socket command except the options can also include any of the applicable tls:import options with 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::protocols: Returns a list of the supported 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.

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. If the callback generates an error, 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

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

CALLBACK OPTIONS

DEBUG

Debug Examples

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

SEE ALSO