tls - binding to OpenSSL toolkit.
package require tls ?1.3?
tls::init ?options?
tls::socket ?options? host
port
tls::socket ?-server command? ?options? port
tls::status channel
tls::handshake channel
tls::import channel ?options?
tls::ciphers
protocol ?verbose?
This extension provides a generic binding to OpenSSL, utilizing the Trf Channel Stacking patch for Tcl 8.[01] and the new Tcl_StackChannel API for Tcl 8.2 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.
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.
- issuer dn
- The distinguished name (DN) of the certificate issuer.
- subject dn
- The distinguished name (DN) of the certificate subject.
- notBefore date
- The begin date for the validity of the certificate.
- notAfter date
- The expiry date for the certificate.
- serial n
- The serial number of the certificate.
- cipher cipher
- The current cipher in use between the client and server channels.
- -cafile filename
- Provide the CA file.
- -cadir dir
- Provide the directory containing the CA certificates.
- -certfile filename
- Provide the certificate to use.
- -cipher string
- Provide the cipher suites to use. Syntax is as per OpenSSL.
- -command callback
- This callback is invoked to pass errors, tracing information and to allow Tcl scripts to perform additional verification of the certificate, which can override the default validation in OpenSSL.
- -keyfile filename
- Provide the private key file. (default: value of -certfile)
- -model channel
- This will force this channel to share the same SSL_CTX structure as the specified channel, and therefore share callbacks etc.
- -request bool
- Request a certificate from peer during SSL handshake. (default: true)
- -require bool
- Require a valid certificate from peer during SSL handshake. If this is set to true then -request must also be set to true. (default: false)
- -server bool
- Handshake as server if true, else handshake as client.(default: false) [Not available to tls::socket]
- -ssl2 bool
- Enable use of SSL v2. (default: true unless -DNO_PATENTS was specified in build)
- -ssl3 bool
- Enable use of SSL v3. (default: true)
- -tls1 bool
- Enable use of TLS v1. (default: false)
In addition to the options listed above you can set the tls::debug flag to a non-zero value to see the output from the default command callback (tls::callback) which shows the progression of the SSL handshake. Setting this value to greated than 1 will cause the default verify method in tls::callback to always accept the certificate, even if it is invalid.
In a real-world deployment you should substitute your own callback in place of tls::callback, via the -command option to tls::socket or tls::import.
When the TLS layer needs to obtain a password, typically for a certificate, the software will invoke a Tcl command called tls::password, which should return a string which represents the password to be used. A default implementation is provided, which simply returns "secret" - you should redefine this procedure after issuing the package require tls.
This example requires a patch to the http module that ships with Tcl - this patch has been submitted for inclusion in Tcl 8.2.1, but is also provided in the tls directory if needed. A sample server.pem is provided with the TLS release, courtesy of the OpenSSL project.
package require http
package require tls
http::register https 443 [list ::tls::socket -require 1 -cafile ./server.pem]
set tok [http::geturl https://developer.netscape.com/]
The capabilities of this package can vary enormously based upon how your OpenSSL library was configured and built. At the most macro-level OpenSSL supports a "no patents" build, which disables RSA, IDEA, RC(2,4,5) and SSL2 - if your OpenSSL is configured this way then you will need to build TLS with the -DNO_PATENTS option - and the resultant module will function correctly and also support ADH certificate-less encryption, however you will be unable to utilize this to speak to normal Web Servers, which typically require RSA support. Please see http://www.openssl.org/ for more information on the whole issue of patents and US export restrictions.
socket, fileevent, OpenSSL
Copyright � 1999 Matt Newman.