SSL/TLS

Secure Sockets Layer and Transport Layer Security Channels

SYNOPSIS

package require twapi_crypto

starttls CHAN ?-server? ?options?

tls_background_error MESSAGE OPTIONDICT

tls_close CHAN ?DIRECTION?

tls_handshake CHAN

tls_socket ?options? REMOTEADDR PORT

tls_socket -server SERVERCALLBACK ?options? PORT

tls_socket_command ?SOCKET_COMMAND?

tls_state CHAN

DESCRIPTION

This module is still experimental and liable to change.

This package provides a Tcl channel facility that implements the Secure Sockets Layer / Transport Layer Security (collectively referred to as TLS) on top of the Windows Security Service Provider Interface (SSPI) interface.

TLS channels

The tls_socket command creates a new TCP/IP based client connection or a listening server socket. The starttls command wraps an existing Tcl bidirectional channel into a TLS channel. The tls_handshake command completes negotiation on a TLS channel. The current channel state can be retrieved with tls_state. Channels are closed using either the tls_close command or the Tcl close command. The former permits half-closing of the output side of the channel which the latter does not allow for reflected channels.

Error handling

Errors that occur in the background are reported by twapi_tls by calling the internal command tls_background_error. This command may be overridden by applications.

Commands

starttls CHAN ?-server? ?options?

Returns a new TLS channel that wraps an existing channel CHAN. CHAN must be in an open state. Caller should use the returned channel and must not access CHAN directly after the command returns, even on errors. By default, the returned channel is for the client end of the connection. If the option -server is specified the channel corresponds to the server end. This impacts how authentication and certificate validation is handled.

The newly returned channel has the same settings for -buffering, -buffersize, -encoding, -eofchar and -translation as the wrapped channel CHAN. The setting for -blocking is also preserved. However, any read or write handlers are not copied to the new channel. The caller must recreate them with chan configure.

The command supports the following options:

-credentials CREDENTIALS	Specifies the credentials to be used for the connection. See tls_socket for details.
-peersubject PEERNAME	Specifies the subject name to be verified on the remote certificate. Must be specified for client side connections and must not be specified for server-side connections.
-verifier VERIFYCOMMAND	Specifies a callback to invoke to verify remote credentials. See tls_socket for details.

tls_background_error MESSAGE OPTIONDICT

This command is internally called by twapi_tls to report errors in event handler during negotiation etc. The default implementation simply raises an exception which causes the event loop to report the error via the bgerror mechanism. An application may override this if it so chooses, for example to log or change the message etc.. However, the application defined command must also raise an exception but has the option of doing so with a different message, error code and options dictionary. If the application defined command returns normally, twapi_tls will itself raise the original exception.

The command is passed the original error message as MESSAGE and the error options dictionary as OPTIONDICT.

tls_close CHAN ?DIRECTION?

Closes the specified TLS channel. This command is similar to the standard Tcl close command except that the latter does not permit half-closing of TLS channels as they are implemented using Tcl's reflected channel framework.

If DIRECTION is not specified, the command behaves identically to the Tcl close command. If DIRECTION is specified, it must currently be the value write or any abbreviation of it. The command will then close the output side of the channel while continuing to allow data to be read from the channel. Currently half-closing of the read side is not supported.

tls_handshake CHAN

If CHAN is a non-blocking TLS channel, the command returns 1 if the TLS negotiation on the channel is completed and 0 if it is still in progress. If CHAN is a blocking channel, for example a channel created with the `-async` option, the command will return only after completing TLS negotiation. The return value will always be 1 in this case. The command will raise an error if TLS negotiation fails or the channel has been closed.

tls_socket ?options? REMOTEADDR PORT

tls_socket -server SERVERCALLBACK ?options? PORT

The tls_socket command provides the same interface as the Tcl socket command except that the connection runs over TLS or SSL.

The first form is used by client-side applications to connect to a remote server running on port PORT at address REMOTEADDR. The latter form is used by server-side applications to listen for incoming connections on port PORT.

The command options include -server, -myaddr, -myport and -async. Please refer to the Tcl documentation of the socket command for the use of these options.

The tls_socket command supports the following additional options:

-credentials CREDENTIALS	Specifies the credentials to be used for the connection. CREDENTIALS should be credentials returned from a call to sspi_acquire_credentials using the -package unisp option. For client-side connections, this option only needs to be specified when connecting to servers that require clients to be authenticated. For server-side connections, this option is usually required for the connection to complete as most remote clients will require validation of server certificates.
-peersubject PEERNAME	Specifies the subject name to be verified on the remote certificate. Only used for client-side connections to verify the name in the certificate returned by the remote server. If unspecified, defaults to REMOTEADDR. This option is silently ignored for server-side connections.
-requestclientcert	Indicates that the client should be asked to send its certificate. Only applicable to server side sockets and is ignored if -server is not specified. Note that this option only results in the client being requested for its certificate. Unlike server certificates, client certificates are not validated by default. Applications must themselves check that a certificate was received and validate it, generally by specifying a verification callback via the -verifier option.
-socketcmd SOCKET_COMMAND	Specifies SOCKET_COMMAND as the command to use to create the underlying TCP socket for this connection in lieu of the command registed with tls_socket_command.
-verifier VERIFYCOMMAND	Specifies a callback to invoke to verify remote credentials. The VERIFYCOMMAND command prefix is invoked with two additional parameters - the channel and a handle to the security context for the connection. If the command returns a true value, the connection is completed. For any other values or errors, the connection is aborted. The callback can retrieve the remote certificate from the passed security context with the sspi_remote_cert command and use cert_tls_verify to validate it. For client-side connections, if this option is specified and is not empty, automatic verification of the server certificate is not done. For server-side connections, automatic verification of client certificates is never done and must be done through this callback.

The channel returned by tls_socket may be used with any of the Tcl channel commands and supports all channel and socket configuration options. In addition, the following read-only configuration options are supported:

-credentials	Returns the handle to the local credentials for the channel.
-context	Returns the handle to the security context for the channel.
-verifier	Returns the verification callback for the channel.

tls_socket_command ?SOCKET_COMMAND?

If no arguments are specified, returns the command used by the extension to create TCP sockets for TLS connections. By default, this is the standard Tcl socket command.

If SOCKET_COMMAND is specified, it is registered as the command to call to create TCP sockets. The return value is the previously registered command.

tls_state CHAN

Returns the current state of a TLS channel. This may be one of CLIENTINIT, SERVERINIT, LISTENER, NEGOTIATING, OPEN or CLOSED.

COPYRIGHT

Copyright © 2013-2020 Ashok P. Nadkarni