tls - binding to OpenSSL +toolkit.
+ +package require Tcl 8.5
+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 is 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 is + 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 is 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 is false)
+- -server bool
+- Handshake as server if true, else handshake as + client.(default is 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 is false)
+- -ssl3 bool
+- Enable use of SSL v3. (default is false)
+- -tls1 bool
+- Enable use of TLS v1. (default is true)
+- -tls1.1 bool
+- Enable use of TLS v1.1 (default is true)
+- -tls1.2 bool
+- Enable use of TLS v1.2 (default is true)
+- -tls1.3 bool
+- Enable use of TLS v1.3 (default is 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://core.tcl-lang.org/]
+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. ++ + DELETED tls.htm Index: tls.htm ================================================================== --- tls.htm +++ /dev/null @@ -1,453 +0,0 @@ - - - - - - - -
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. -- -