@@ -19,11 +19,11 @@ for socket and I/O channel communications.
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()
.This example uses the default Unix platform SSL certificates. For standard +installations, -cadir and -cafile should not be needed. Update -cadir or +replace with -cafile if your platform differs.
+
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]
-set token [http::geturl "https://www.tcl-lang.org/"]
+# 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
-Example #2:
+Example #2: Use raw socket
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 h2} -cadir /etc/ssl/certs -command ::tls::callback \
+ -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"
@@ -721,20 +750,32 @@
This example uses a sample server.pem provided with the TLS release, -courtesy of the OpenSSL project.
+This example uses the default Unix platform SSL certificates. For standard +installations, -cadir and -cafile should not be needed. Update -cadir or +replace with -cafile if your platform differs.
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]
-set token [http::geturl https://www.tcl.tk/]
+# 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