SSL/TLS

Secure Sockets Layer and Transport Layer Security Channels

SYNOPSIS

package require twapi_crypto

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 on top of the Windows Security Service Provider Interface (SSPI) interface.

SSL/TLS channels

The module implements a single command, tls_socket, that implements a SSL/TLS based channel which can be used with all Tcl channel based commands like puts, read, chan.

Commands

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