@@ -3,13 +3,11 @@ - - + TLS (SSL) Tcl Commands @@ -114,12 +112,12 @@ the handshake was successful. If the handshake failed this routine will throw an error.
 
tls::status ?-local? channel
-
Returns the current security status of a SSL channel. The - result is a list of key value pairs describing the +
Returns the current security status of an SSL channel. The + result is a list of key-value pairs describing the connected peer. If the result is an empty list then the SSL handshake has not yet completed. If -local is given, then the certificate information is the one used locally.
@@ -154,27 +152,25 @@ setting session parameters for SSL handshake.
-
-cadir dir
+
-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
+
-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: @@ -181,13 +177,14 @@ 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
+
-password callback
If supplied, this callback will be invoked when OpenSSL needs - to obtain a password, typically for a certificate. + to obtain a password, typically to unlock the private key of + a certificate. The callback should return a string which represents the password to be used.
See CALLBACK OPTIONS for further discussion.
@@ -234,36 +231,150 @@ to handle intermediate processing by the OpenSSL library, using the -command and -password options passed to either of tls::socket or tls::import.

+
+
+ +
-command callback
+
+ Invokes the specified callback script at + several points during the OpenSSL handshake. + Except as indicated below, values returned from the + callback are ignored. + Arguments appended to the script upon callback take one of the + following forms: + +
+
+ +
+ + + +
+ info channel major minor message +
+
+ This form of callback is invoked by the OpenSSL function + SSL_CTX_set_info_callback(). +
+ The major and minor arguments are used to + represent the state information bitmask. +
+
Possible values for major are:
+
handshake, alert, connect, accept.
+
Possible values for minor are:
+
start, done, read, write, loop, exit.
+
+ The message argument is a descriptive string which may + be generated either by + SSL_state_string_long() or by + SSL_alert_desc_string_long(), + depending on context. +
+ +
+ +
+ verify channel depth cert status error +
+
+ This form of callback is invoked by the OpenSSL function + SSL_set_verify(). +
+ The depth argument is an integer representing the + current depth on the certificate chain, with + 0 as the subject certificate and higher values + denoting progressively more indirect issuer certificates. +
+ The cert argument is a list of key-value pairs similar + to those returned by + tls::status. +
+ The status argument is an integer representing the + current validity of the certificate. + A value of 0 means the certificate is deemed invalid. + A value of 1 means the certificate is deemed valid. +
+ The error argument supplies the message, if any, generated + by + X509_STORE_CTX_get_error(). +
+
+ The callback may override normal validation processing by explicitly + returning one of the above status values. +
+ +
+
+ +
+ +
-password callback
+
+ Invokes the specified callback script when OpenSSL needs to + obtain a password. The callback should return a string which + represents the password to be used. + No arguments are appended to the script upon callback. +
+
+
+

-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. +Reference implementations of these callbacks are provided in the +distribution as tls::callback and +tls::password respectively. Note that these are +sample implementations only. In a more realistic deployment +you would specify your own callback scripts on each TLS channel +using the -command and -password options.

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. +compatibility with earlier implementations. +

+ +

+The tls::debug variable provides some additional +control over these reference callbacks. Its value is zero by default. +Higher values produce more diagnostic output, and will also force the +verify method in tls::callback to accept the +certificate, even when it is invalid. +

+ +

+ +The use of the reference callbacks tls::callback and +tls::password is not recommended. They may be removed +from future releases. +

-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. + +The use of the variable tls::debug is not recommended. +It may be removed from future releases. +

HTTPS EXAMPLE

This example requires a patch to the http @@ -270,11 +381,12 @@ 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 http
 package require tls
 
 http::register https 443 [list ::tls::socket -require 1 -cafile ./server.pem]
 
 set tok [http::geturl https://developer.netscape.com/]
@@ -302,8 +414,9 @@
 
 

 
 
 Copyright © 1999 Matt Newman.
+Copyright © 2004 Starfish Systems.