SSLtcl – a loadable module that extends the tcl socket command with SSL
load $PATH/SLtcl.so SSLtcl
socket [-myaddr addr] [-myport myport] [-async] [-ssl [-verify NUM] [-cert Certificate] [-key privateKey] [-CAfile CAfile] [-CAdir CAdir] ] host port
socket -server command [-ssl -cert Certificate [-key privateKey] [-verify NUM] [-Verify NUM] [-CAfile CAfile] [-CAdir CAdir] [-myaddr addr] port
SSLtcl creates a new tcl socket command with SSL capabilities. Se socket(n) for a description of the tcl socket command. Used with -ssl option it creates a SSL based connection. If -ssl is left out it function as the normal socket command and only options described in socket(n) is available. SSLtcls socket creates either a server SSL socket or a client SSL socket, exactly as the normal socket command.
If the -server option is not specified, then the client side of a connection is opened and the command returns a channel identifier that can be used for both reading and writing. Port and host specify a port to connect to; there must be a server accepting connections on this port. Port is an integer port number and host is either a domain-style name such as www.sunlabs.com or a numerical IP address such as 127.0.0.1. Use localhost to refer to the host on which the command is invoked. The following options may also be present before host to specify additional information about the connection:
Addr gives the domain-style name or numerical IPaddress of the client-side network interface to use for the connection. This option may be useful if the client machine has multiple network interfaces. If the option is omitted then the client-side interface will be chosen by the system software.
Port specifies an integer port number to use for the client's side of the connection. If this option is omitted, the client's port number will bechosen at random by the system software.
The -async option will cause the client socket to be connected asynchronously. This means that the socket will be created immediately but may not yet be connected to the server, when the call to socket returns. When a gets or flush is done on the socket before the connection attempt succeeds or fails, if the socket is in blocking mode, the operation will wait until the connection is completed or fails. If the socket is in nonblocking mode and a gets or flush is done on the socket before the connection attempt succeeds or fails, the operation returns immediately and fblocked on the socket returns 1.
The -ssl option turns SSL on an makes the following options available.
Turns verification of server on. num is an integer that specifies how deep in the certificate chain verification is required to succeed.
Specifies the private key that accompanies the own certificate. A certificate is only required for the client if it is going to be verified by the server. If left out will be set to the same value as given for -cert.
The client certificate, pem encoded, that it will send to the server if required.
A file containing certificates from Certificate Authorities that the client wants to trust. To verify a server a CAfile, or a CAdir, is required.
A hashed directory that contains certificates from Certificate Authorities that the client wants to trust. To verify a server a CAdir, or a CAfile, is required.
cipherlist is a colon separated list of ciphers that the clients wants to support. The first one will be tried first, and so on. See Supported ciphers below.
If the -server option is specified then the new socket will be a server for the port given by port. Tcl will automatically accept connections to the given port. For each connection Tcl will create a new channel that may be used to communicate with the client. Tcl then invokes command with three additional arguments: the name of the new channel, the address, in network address notation, of the client's host, and the client's port number. The following additional option may also be specified before host:
Addr gives the domain-style name or numerical IP address of the server-side network interface to use for the connection. This option may be useful if the server machine has multiple network interfaces. If the option is omitted then the server socket is bound to the special address INADDR_ANY so that it can accept connections from any interface.
The -ssl option turns SSL on an makes the following options available.
Turns verification of client on. num is an integer that specifies how deep in the certificate chain verification is required to succeed. Will only report verification result, not stop the connection
Same as -verify, but will stop the connection if verify fails.
Specifies the private key that accompanies the server certificate. If left out will be set to the same value as given for -cert.
The server certificate, pem encoded; it is required.
A file contaning certificates from Certificate Authorities that the server wants to trust. To verify a client a CAfile, or a CAdir, is required.
A hashed directory that contains certificates from Certificate Authorities that the server wants to trust. To verify a client a CAdir, or a CAfile, is required.
cipherlist is a colon separated list of ciphers that the server wants to support. The first one will be tried first, and so on. See Supported ciphers below.
Specififies the numer of times the server should try to accept a connection. num is an integer. The defaultvalue is 100000. The option exist because of a problem with non SSL aware clients and server socket in non -blocking mode. Without a timeout the server will block for ever. I will try to find a better solution in the furure. If releveant connections keeps returning with bgerror try to increase this value.
Server channels cannot be used for input or output; their sole use is to accept new client connections. The channels created for each incoming client connection are opened for input and output. Closing the server channel shuts down the server so that no new connections will be accepted; however, existing connections will be unaffected. Server sockets depend on the Tcl event mechanism to find out when new connections are opened. If the application doesn't enter the event loop, for example by invoking the vwait command or calling the C procedure Tcl_DoOneEvent, then no connections will be accepted.
The cipeherslist is specified as a colon separated list of ciphers. The following cipherabrewations, and is supported:
RC4-MD5
EXP-RC4-MD5
IDEA-CBC-MD5
RC2-CBC-MD5
EXP-RC2-CBC-MD5
DES-CBC-MD5
DES-CBC-SHA
DES-CBC3-MD5
DES-CBC3-SHA
DES-CFB-M1
NULL-MD5
If You link SSLtcl against SSLeay-0.8.1 have a look in ssl.h for aditional ciphers.
In the SSLtcl distribution there are several scripts that can be used to understand how sockets and sockets with ssl could be used. tstSrc.tcl and tstCli.tcl is two small scripts with blocking IO using SSL that used connects and drop the connection. tstSrvReal.tcl and tstCliReal.tcl uses fileevent and nonblocking with SSL. This means You can establish several simultaneous connection with the server and send messages from the clients to the server. tstSrvRealNoSSL.tcl and tstCliRealNoSSL.tcl are the same as the previous scripts, except that SSL is left out.
You may have to change the path to tclsh8.0 and to SSLtcl.so to get it to work. To generate own certificates to work with, see the SSLtcl documentation.
SSLtcl is still under development and may contain bug or badly implemented solutions. Contact the author if something strange happens.
Peter Antman (peter.antman@abc.se)
SSLtcl is based on tclSSL, an earlier work by Tony Bringardner. SSLtcl is heavily updated compared to tclSSL but owes its basic structure and ideas to tclSSL.
SSLtcl is also based on the work by Eric Young, specially s_server and s_client, and Ben Lauries SSL patch to apache.
Thank You all.
socket(n), and the SSLeay documentation.