TLS (SSL) Tcl Commands

@@ -1,40 +1,37 @@ - - - - + + +content="text/html; charset=utf-8"> TLS (SSL) Tcl Commands

NAME

tls - binding to OpenSSL - toolkit.

- +

NAME +

tls - binding to OpenSSL toolkit.

SYNOPSIS

package require Tcl ?8.4?; package require tls ?@@VERS@@?
: tls::init ?options?; tls::socket ?options? host port; tls::socket ?-server command? - ?options? port; tls::handshake channel; tls::status ?-local? channel; tls::import channel ?options?; tls::unimport channel; tls::ciphers protocol ?verbose?; tls::version

package require Tcl ?8.5?

package require tls ?@@VERS@@?

tls::init ?options?

tls::socket ?options? host port

tls::socket ?-server command? ?options? port

tls::handshake channel

tls::status ?-local? channel

tls::import channel ?options?

tls::unimport channel

tls::ciphers protocol ?verbose?

tls::version

COMMANDS

CALLBACK OPTIONS

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

@@ -48,22 +45,22 @@

tls - binding to OpenSSL toolkit.

SYNOPSIS

package require Tcl 8.4
+

package require Tcl 8.5
package require tls @@VERS@@

-tls::init ?options?
-tls::socket ?options? host +tls::init ?options?
+tls::socket ?options? host port
tls::socket ?-server command? ?options? port
-tls::status ?-local? channel
+tls::status ?-local? channel
tls::handshake channel

-tls::import channel ?options?
-tls::unimport channel
+tls::import channel ?options?
+tls::unimport channel
tls::ciphers protocol ?verbose?
tls::version

@@ -85,174 +82,174 @@ which provides compatibility with the native Tcl socket command. In such cases tls::import should not be used directly.

-
tls::init ?options?
+
tls::init ?options?

This routine sets the default options used by tls::socket - and is optional. If you call tls::import - directly this routine has no effect. Any of the options - that tls::socket accepts can be set - using this command, though you should limit your options - to only TLS related ones.
+ and is optional. If you call tls::import + directly this routine has no effect. Any of the options + that tls::socket accepts can be set + using this command, though you should limit your options + to only TLS related ones.

-
tls::socket ?options? - host port
+
tls::socket ?options? + host port

tls::socket ?-server command? ?options? port

This is a helper function that utilizes the underlying - commands (tls::import). It behaves - exactly the same as the native Tcl socket - command except that the options can include any of the - applicable tls:import - options with one additional option: + commands (tls::import). It behaves + exactly the same as the native Tcl socket + command except that the options can include any of the + applicable tls:import + options with one additional option:

-
-autoservername bool
-
Automatically send the -servername as the host argument - (default: false)
+
-autoservername bool
+
Automatically send the -servername as the host argument + (default is false)

tls::handshake channel

Forces handshake to take place, and returns 0 if - handshake is still in progress (non-blocking), or 1 if - the handshake was successful. If the handshake failed - this routine will throw an error.
+ handshake is still in progress (non-blocking), or 1 if + the handshake was successful. If the handshake failed + this routine will throw an error.

tls::status ?-local? channel

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.
+ 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.

-
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: +
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

-
tls::import channel - ?options?
+
tls::import channel + ?options?

SSL-enable a regular Tcl channel - it need not be a - socket, but must provide bi-directional flow. Also - setting session parameters for SSL handshake.
+ socket, but must provide bi-directional flow. Also + setting session parameters for SSL handshake.

-
-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 +
-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: 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 + 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: 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)
+
-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)

-
tls::unimport channel
+
tls::unimport channel

Provided for symmetry to tls::import, this unstacks the SSL-enabling of a regular Tcl channel. An error is thrown if TLS is not the top stacked channel type.

tls::ciphers - protocol ?verbose?
+ protocol ?verbose?
Returns list of supported ciphers based on the protocol - you supply, which must be one of ssl2, ssl3, or tls1. - If verbose is specified as true then a verbose, - semi-human readable list is returned providing additional - information on the nature of the cipher support. In each - case the result is a Tcl list.
+ you supply, which must be one of ssl2, ssl3, or tls1. + If verbose is specified as true then a verbose, + semi-human readable list is returned providing additional + information on the nature of the cipher support. In each + case the result is a Tcl list.

tls::version

Returns the version string defined by OpenSSL.
@@ -418,11 +415,11 @@ 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/] +set tok [http::geturl https://core.tcl-lang.org/]
SPECIAL CONSIDERATIONS

The capabilities of this package can vary enormously based @@ -438,11 +435,11 @@ more information on the whole issue of patents and US export restrictions.

SEE ALSO
-
socket, fileevent, socket, fileevent, OpenSSL