tls - binding to OpenSSL -toolkit.
- -package require Tcl 8.2
-package require tls 1.4
-
-tls::init ?options?
-tls::socket ?options? host
-port
-tls::socket ?-server command? ?options? port
-tls::status ?-local? channel
-tls::handshake channel
-
-tls::import channel ?options?
-tls::ciphers
-protocol ?verbose?
This extension provides a generic binding to OpenSSL, utilizing the -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. -To use TLS with an earlier version of Tcl than 8.2, please obtain -TLS v1.3. Please note that there are known limitations with the -stacked channel implementation prior to 8.3.2, so it is recommended -that TLS is used with an 8.3.2+ interpreter. TLS v1.4 will work -with 8.2+, it is just more stable with 8.3.2+. -
- -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.
-- sbits n
-- The number of bits used for the session key.
-
-- --
-- -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.- - + + + + + + + + +
tls - binding to OpenSSL +toolkit.
+ +package require Tcl 8.2
+package require tls 1.4
+
+tls::init ?options?
+tls::socket ?options? host
+port
+tls::socket ?-server command? ?options? port
+tls::status ?-local? channel
+tls::handshake channel
+
+tls::import channel ?options?
+tls::ciphers
+protocol ?verbose?
+tls::version
+
This extension provides a generic binding to OpenSSL, utilizing the +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. +To use TLS with an earlier version of Tcl than 8.2, please obtain +TLS v1.3. Please note that there are known limitations with the +stacked channel implementation prior to 8.3.2, so it is recommended +that TLS is used with an 8.3.2+ interpreter. TLS v1.4 will work +with 8.2+, it is just more stable with 8.3.2+. +
+ +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.
+- sbits n
+- The number of bits used for the session key.
+
++ ++
+- -cadir dir
+- Provide the directory containing the CA certificates.
+- -cafile filename
+- Provide the CA file.
+- -certfile filename
+- Provide the certificate to use.
+- -cipher string
+- Provide the cipher suites to use. Syntax is as per + OpenSSL.
+- -command callback
+- If specified, this callback will be invoked at several points + during the OpenSSL handshake. It can pass errors and tracing + information, and it can allow Tcl scripts to perform + their own validation of the certificate in place of the + default validation provided by OpenSSL. + The callback should return an integer whose interpretation + depends on context. +
+
+ See CALLBACK OPTIONS for + further discussion.- -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.
+- -password callback
+- If supplied, this callback will be invoked when OpenSSL needs + to obtain a password, typically for a certificate. + The callback should return a string which represents the + password to be used. +
+
+ See CALLBACK OPTIONS for + further discussion.- -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)
+- -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)
+
+As indicated above, individual channels can be given their own callbacks +to handle intermediate processing by the OpenSSL library, using the +-command and -password options passed to either of +tls::socket or tls::import. +
+ ++Reference implementations of these callbacks are provided in the distribution +as tls::callback and tls::password. +Note that these are sample implementations only. In a more realistic +deployment you would substitute your own callbacks, typically by configuring +the -command and -password options on each channel with +scripts to be executed when the callbacks are invoked. +
+ ++The default behavior when the -command option is not specified is for +TLS to process the associated library callbacks internally. +The default behavior when the -password option is not specified is for +TLS to process the associated library callbacks by attempting to call +tls::password. +The difference between these two behaviors is a consequence of maintaining +compatibility with earlier implementations. The use of implied callbacks +is not recommended. +
+ ++The tls::debug variable provides some additional control +over the default commands. Its value is zero by default. Higher values +produce more diagnostic output. Setting this value greater than zero +will also force the default verify method in tls::callback +to accept the certificate, even if it is invalid. +
+ +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. ++ +