Version is the protocol version.

[def [arg content_type]]
Content type is the message content type.

[def [arg message]]
Message is more info from the [const SSL_trace] API.
This argument is new for TclTLS 1.8.

[list_end]

[opt_def session [arg "channelId session_id session_ticket lifetime"]]
This form of callback is invoked by the OpenSSL function
[fun SSL_CTX_sess_set_new_cb()] whenever a new session id is sent by the
server during the initial connection and handshake and also during the session

[def [arg lifetime]]
Lifetime is the ticket lifetime in seconds.

[list_end]

[opt_def verify [arg "channelId depth cert status error"]]
This callback was moved to the [option -verify_callback] in TclTLS 1.8.

[list_end]

[subsection "Values for Password Callback"]

The callback for the [option -password] option is invoked by TclTLS whenever OpenSSL needs
to obtain a password. See below for the possible arguments passed to the

[emph "The use of the variable [var tls::debug] is not recommended.
It may be removed from future releases."]

[section "Debug Examples"]

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.

[para]

Example #1: Use HTTP package

[example {

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]]
}

[example {

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]

[example {

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]]
}

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]

# Get file
set ch [open $filename wb]
set token [::http::geturl $url -blocksize 65536 -channel $ch]

# Cleanup
close $ch