tls - binding to OpenSSL -toolkit.
- -package require Tcl 8.4
-package require tls @@VERS@@
-
-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::unimport channel
-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.4, please obtain -TLS 1.3. -
- -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.
- ----
-- -autoservername bool
-- Automatically send the -servername as the host argument - (default: false)
-
-- --
-- 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.
-- certificate n
-- The PEM encoded certificate.
-- version value
-- The protocol version used for the connection: - SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, unknown
-
-- --
-- -cadir dir
-- Provide the directory containing the CA certificates.
-- -cafile filename
-- Provide the CA file.
-- -certfile filename
-- Provide the name of a file containing certificate to use.
-- -cert filename
-- Provide the contents of a certificate to use, as a DER encoded binary value (X.509 DER).
-- -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. -
-
- See CALLBACK OPTIONS for - further discussion.- -dhparams filename
-- Provide a Diffie-Hellman parameters file.
-- -keyfile filename
-- Provide the private key file. (default: - value of -certfile)
-- -key filename
-- Provide the private key to use as a DER encoded value (PKCS#1 DER)
-- -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 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.- -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)
-- -servername host
-- Only available if the OpenSSL library the package is linked - against supports the TLS hostname extension for 'Server Name - Indication' (SNI). Use to name the logical host we are talking - to and expecting a certificate for
-- -ssl2 bool
-- Enable use of SSL v2. (default: false)
-- -ssl3 bool
-- Enable use of SSL v3. (default: false)
-- -tls1 bool
-- Enable use of TLS v1. (default: true)
-- -tls1.1 bool
-- Enable use of TLS v1.1 (default: true)
-- -tls1.2 bool
-- Enable use of TLS v1.2 (default: true)
-- -tls1.3 bool
-- Enable use of TLS v1.3 (default: true)
-
-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. -
- --- -- -
-- -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. --
- The message argument is a descriptive string which may - be generated either by -- Possible values for major are:
-- -
handshake, alert, connect, accept.- Possible values for minor are:
-- -
start, done, read, write, loop, exit.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 -0as 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 of0means the certificate is deemed invalid. - A value of1means 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 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 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 use of the variable tls::debug is not recommended. -It may be removed from future releases. - -
- -This example uses a sample server.pem provided with the TLS release, -courtesy of the OpenSSL project.
- -
-package require http
-package require tls
-
-http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs]
-
-set tok [http::geturl https://www.tcl.tk/]
-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. -Copyright © 2004 Starfish Systems. -- -