SSL/TLS

Secure Sockets Layer and Transport Layer Security Channels

SYNOPSIS

package require twapi_crypto

starttls CHAN -server ?options?

tls_socket ?options? REMOTEADDR PORT

tls_socket -server SERVERCALLBACK ?options? PORT

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 module implements two commands tls_socket and starttls which implement TLS based channels which can be used with all Tcl channel based commands like puts, read, chan. The tls_socket command creates a new TCP/IP based connection while the starttls command wraps an existing plaintext channel.

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

COPYRIGHT

Copyright © 2013 Ashok P. Nadkarni