tls - binding to OpenSSL library for socket and I/O channel communications.
package require Tcl 8.5
+
package require Tcl ?8.5?
package require tls
tls::init ?options?
tls::socket ?options? host port
tls::socket ?-server command? ?options? port
@@ -69,16 +69,17 @@
tls::version
This extension provides a generic binding to OpenSSL, utilizing the -Tcl_StackChannel -API for Tcl 8.4 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. +
This extension provides TCL script access to secure socket communications +using the Transport Layer Security (TLS) protocol. It provides a generic +binding to OpenSSL, utilizing the +Tcl_StackChannel API in Tcl 8.4 and higher. +These sockets behave exactly the same as channels created using the built-in +socket command, along with additional options for controlling +the SSL session.
Typically one would use the tls::socket command
@@ -459,26 +460,29 @@
ERR_reason_error_string().
+ This form of callback is invoked whenever an error occurs during the
+ initial connection, handshake, or I/O operations. The message
+ argument can be from the Tcl_ErrnoMsg, OpenSSL function
+ ERR_reason_error_string(), or a custom message.
SSL_CTX_set_info_callback() during connection setup
- and use.
+ SSL_set_info_callback() during the initial connection
+ and handshake operations. The type argument is new for
+ TLS 1.8. The arguments are:
handshake, alert, connect, accept.info is used.SSL_set_msg_callback() whenever a message is sent or
- received. It is only available when
- OpenSSL is complied with the enable-ssl-trace option.
- Where direction is Sent or Received, version is the
- protocol version, content_type is the message content type,
- and data is more info on the message from the SSL_trace API.
+ received during the initial connection, handshake, or I/O operations.
+ It is only available when OpenSSL is complied with the
+ enable-ssl-trace option. Arguments are: direction
+ is Sent or Received, version is the protocol
+ version, content_type is the message content type, and
+ message is more info from the SSL_trace API.
+ This callback is new for TLS 1.8.
SSL_CTX_sess_set_new_cb().
- Where session_id is the current session identifier,
- ticket is the session ticket info, and lifetime
- is the the ticket lifetime in seconds.
+ SSL_CTX_sess_set_new_cb() whenever a new session id is
+ sent by the server during the initial connection and handshake, but
+ can also be received later if the -post_handshake option is
+ used. Arguments are: session_id is the current
+ session identifier, ticket is the session ticket info, and
+ lifetime is the the ticket lifetime in seconds.
+ This callback is new for TLS 1.8.
0 as the peer certificate and higher values going
- up to the Certificate Authority (CA).0 means the certificate is deemed invalid.
- A value of 1 means the certificate is deemed valid.X509_STORE_CTX_get_error().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. +certificate, even when it is invalid if the tls::validate_command +callback is used for the -validatecommand option.
The use of the variable tls::debug is not recommended. It may be removed from future releases.
+ +These examples use the default Unix platform SSL certificates. For standard +installations, -cadir and -cafile should not be needed. If your certificates +are in non-standard locations, update -cadir or use -cafile as needed.
+
+package require http
+package require tls
+set url "https://www.tcl.tk/"
+
+http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs \
+ -command ::tls::callback -password ::tls::password -validatecommand ::tls::validate_command]
+
+# Check for error
+set token [http::geturl $url]
+if {[http::status $token] ne "ok"} {
+ puts [format "Error %s" [http::status $token]]
+}
+
+# Get web page
+set data [http::data $token]
+puts [string length $data]
+
+# Cleanup
+::http::cleanup $token
+
+package require tls
+
+set url "www.tcl-lang.org"
+set port 443
+
+set ch [tls::socket -autoservername 1 -servername $url -request 1 -require 1 \
+ -alpn {http/1.1} -cadir /etc/ssl/certs -command ::tls::callback \
+ -password ::tls::password -validatecommand ::tls::validate_command $url $port]
+chan configure $ch -buffersize 65536
+tls::handshake $ch
+
+puts $ch "GET / HTTP/1.1"
+flush $ch
+after 500
+set data [read $ch]
+
+array set status [tls::status $ch]
+array set conn [tls::connection $ch]
+array set chan [chan configure $ch]
+close $ch
+parray status
+parray conn
+parray chan
+This example uses a sample server.pem provided with the TLS release, -courtesy of the OpenSSL project.
+These examples use the default Unix platform SSL certificates. For standard +installations, -cadir and -cafile should not be needed. If your certificates +are in non-standard locations, update -cadir or use -cafile as needed.
+ +Example #1: Get web page + +
+package require http
+package require tls
+set url "https://www.tcl.tk/"
+
+http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs]
+
+# Check for error
+set token [http::geturl $url]
+if {[http::status $token] ne "ok"} {
+ puts [format "Error %s" [http::status $token]]
+}
+
+# Get web page
+set data [http::data $token]
+puts $data
+
+# Cleanup
+::http::cleanup $token
+
package require http
package require tls
+
+set url "https://wiki.tcl-lang.org/sitemap.xml"
+set filename [file tail $url]
http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs]
-set tok [http::geturl https://www.tcl.tk/]
+# Get file
+set ch [open $filename wb]
+set token [::http::geturl $url -blocksize 65536 -channel $ch]
+
+# Cleanup
+close $ch
+::http::cleanup $token
The capabilities of this package can vary enormously based upon how the @@ -702,16 +810,17 @@ Use the tls::protocols commands to obtain the supported protocol versions.
socket, fileevent, OpenSSL
+socket, fileevent, http, +OpenSSL
Copyright © 1999 Matt Newman. Copyright © 2004 Starfish Systems. +Copyright © 2023 Brian O'Hagan.