TLS (SSL) Tcl Commands

NAME

tls - binding to OpenSSL toolkit.

SYNOPSIS

package require Tcl ?8.4?; 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::cipher name; tls::ciphers ?protocol? ?verbose? ?supported?; tls::digests ?name?; tls::macs; tls::protocols; tls::version
: tls::digest -digest name ?options?; tls::cmac -cipher name -key key ?options?; tls::hmac -digest name -key key ?options?; tls::md4 data; tls::md5 data; tls::sha1 data; tls::sha256 data; tls::sha512 data

COMMANDS

CALLBACK OPTIONS

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

NAME

tls - binding to OpenSSL toolkit.

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::cipher name
tls::ciphers ?protocol? ?verbose? ?supported?
tls::digests ?name?
tls::macs
tls::protocols
tls::version

tls::digest -digest name ?options?
tls::cmac -cipher name -key key ?options?
tls::hmac -digest name -key key ?options?
tls::md4 data
tls::md5 data
tls::sha1 data
tls::sha256 data
tls::sha512 data

This extension provides a generic binding to OpenSSL, utilizing the Tcl_StackChannel API for Tcl 8.4 and higher. The sockets behave exactly the same as channels created using Tcl's built-in socket command 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 that the options can include any of the applicable tls:import options with one additional option:
tls::import channel ?options?: SSL-enable a regular Tcl channel - it need not be a socket, but must provide bi-directional flow. Also setting session parameters for SSL handshake.
tls::unimport channel: Provided for symmetry to tls::import, this unstacks the SSL-enabling 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 the certificate for an SSL channel. The result is a list of key-value pairs describing the certificate. 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 connected peer.
tls::cipher name: Return a list of property names and values describing cipher name. Properties include name, description, block_size, key_length, iv_length, type, and mode list.
tls::ciphers ?protocol? ?verbose? ?supported?: Without any args, returns a list of all ciphers. 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::digests ?name?: Without name, returns a list of the supported hash algorithms for tls::digest command. With name, returns a list of property names and values describing digest name. Properties include name, description, size, block_size, type, and flags list.
tls::macs: Returns a list of the available Message Authentication Codes (MAC) for the tls::digest command.
tls::protocols: Returns a list of 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.
tls::digest -digest name ?-bin|-hex? [-file filename | -command cmdName | -chan channelId | -data data]: Calculate the message digest (MD) of data using name hash function and return the resulting hash value as a hex string (default) or as a binary value with -bin or -binary option. MDs are used to ensure the integrity of data. The hash function can be any supported OpenSSL algorithm such as md4, md5, sha1, sha256, sha512, sha3-256, etc. See tls::digests command for a full list. In OpenSSL 3.0+, older algorithms may reside in the legacy provider.
Using the -data option will immediately return the message digest for data in the specified format. Example code:
set md [::tls::digest sha256 "Some example data."]
Using the -file or -filename option will open file filename, read the file data, close the file, and return the message digest in the specified format. This uses the TCL APIs, so VFS files are supported. Example code:
set md [::tls::digest -digest sha256 -file test_file.txt]
Using the -chan or -channel option, a stacked channel is created for channelId and data read from the channel is used to calculate a message digest with the result returned with the last read operation before EOF. Channel is automatically set to binary mode. Example code:
set ch [open test_file.txt r] ::tls::digest -digest sha256 -chan $ch while {![eof $ch]} {set md [read $ch 4096]} close $ch
Using the -command option, a new command cmdName is created and returned. To add data to the hash function, call "cmdName update data", where data is the data to add. When done, call "cmdName finalize" to return the message digest. Example code:
set cmd [::tls::digest -digest sha256 -command ::tls::temp] $cmd update "Some data. " $cmd update "More data." set md [$cmd finalize]
tls::cmac -cipher name -key key ?-bin|-hex? [-file filename | -command cmdName | -chan channelId | -data data]: Calculate the Cipher-based Message Authentication Code (CMAC). MACs are used to ensure authenticity and the integrity of data. It uses the same options as tls::digest, plus the additional option -cipher to specify the cipher to use and for certain ciphers, -key to specify the key.
tls::hmac -digest name -key key ?-bin|-hex? [-file filename | -command cmdName | -chan channelId | -data data]: Calculate the Hash-based Message Authentication Code (HMAC). HMACs are used to ensure the data integrity and authenticity of a message using a shared secret key. The cryptographic strength depends upon the size of the key and the security of the hash function used. It uses the same options as tls::digest, plus additional option -key to specify the key to use. To salt a password, append or prepend the salt data to the password.
tls::mac -cipher name -digest name -key key ?-bin|-hex? [-file filename | -command cmdName | -chan channelId | -data data]: (OpenSSL 3.0+) Calculate the Message Authentication Code (MAC). MACs are used to ensure authenticity and the integrity of data. It uses the same options as tls::digest, plus the additional options -cipher to specify the cipher to use, -digest to specify the digest, and for certain ciphers, -key to specify the key.
tls::md4 data: Returns the MD4 message-digest for data as a hex string.
tls::md5 data: Returns the MD5 message-digest for data as a hex string.
tls::sha1 data: Returns the SHA1 secure hash algorithm digest for data as a hex string.
tls::sha256 data: Returns the SHA-2 SHA256 secure hash algorithm digest for data as a hex string.
tls::sha512 data: Returns the SHA-2 SHA512 secure hash algorithm digest for data as a hex 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 with 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 channel message

The message argument contains an error message generated by the OpenSSL function ERR_reason_error_string().

info channel major minor message type

This form of callback is invoked by the OpenSSL function SSL_CTX_set_info_callback() during connection setup and use.

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 channel direction version content_type data

This form of callback is invoked by the OpenSSL function SSL_set_msg_callback() whenever a message is sent or received. It is only available when OpenSSL is complied with the enable-ssl-trace option. Where direction is Sent or Received, version is the protocol version, content_type is the message content type, and data is more info on the message from the SSL_trace API.

session channel session_id ticket lifetime

This form of callback is invoked by the OpenSSL function SSL_CTX_sess_set_new_cb(). Where session_id is the current session identifier, ticket is the session ticket info, and lifetime is the the ticket lifetime in seconds.

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

-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. To reject the value and abort 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 channel 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 specified protocol common to the both the client and server. If not, the first client specified protocol is used. Called after hello and ALPN callbacks.

hello channel servername

For servers, this form of callback is invoked during client hello message processing. It is used to select an appropriate certificate to present, and make other configuration adjustments relevant to that server name and its configuration. Called before SNI and ALPN callbacks.

sni channel servername

For servers, this form of callback is invoked when the SNI extension from the client is received. Where servername is the client provided server name from the -servername option. This is used when a server supports multiple names, so the right certificate can be used. Called after hello callback but before ALPN callback.

verify channel 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 an integer representing the current depth on the certificate chain, with 0 as 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 an boolean representing the validity of the current certificate. A value of 0 means the certificate is deemed invalid. A value of 1 means the certificate is deemed valid.

The error argument supplies the 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 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.

The use of the reference callbacks tls::callback, tls::password, and tls::validate_command is not recommended. They may be removed from future releases.

The use of the variable tls::debug is not recommended. It 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.

HTTPS EXAMPLE

This example uses a sample server.pem provided with the TLS release, courtesy of the OpenSSL project.


package require http
package require tls

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

set tok [http::geturl https://www.tcl.tk/]

SPECIAL CONSIDERATIONS

The capabilities of this package can vary enormously based upon how your OpenSSL library was configured and built. New versions may obsolete older protocol versions, add or remove ciphers, change default values, etc. Use the tls::ciphers and tls::protocols commands to obtain the supported versions.

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

CALLBACK OPTIONS

DEBUG

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

SEE ALSO