\fB--enable-debug\fR can be used to get detailed execution flow status\&.
.PP
TLS key logging can be enabled by setting the environment variable
\fBSSLKEYLOGFILE\fR to the name of the file to log to\&. Then whenever TLS key
material is generated or received it will be logged to the file\&. This is useful
for logging key data for network logging tools to use to decrypt the data\&.
.PP
The \fBtls::debug\fR 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 \fBtls::callback\fR
to accept the certificate, even when it is invalid if the
\fB-validatecommand\fR option is set to \fBtls::validate_command\fR\&.
The \fBtls::debug\fR variable provides some additional control over the
debug logging in the \fBtls::callback\fR, \fBtls::password\fR, and
\fBtls::validate_command\fR default handlers in "\fItls\&.tcl\fR"\&.
The default value is 0 with higher values producing more diagnostic output,
and will also force the verify method in \fBtls::callback\fR to accept the
certificate, even if it is invalid when the \fB-validatecommand\fR
option is set to \fBtls::validate_command\fR\&.
.PP
\fIThe use of the variable \fBtls::debug\fR is not recommended\&.
It may be removed from future releases\&.\fR
.SH "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, specify -cadir or -cafile as needed\&. See the
demos directory for more elaborate examples\&.
.SH "HTTP PACKAGE EXAMPLES"
The following are example scripts to download a webpage and file using the
http package\&. See \fBCertificate Validation\fR for whether the
\fB-cadir\fR, \fB-cafile\fR, and \fB-castore\fR options are also
needed\&. See the demos directory for more example scripts\&.
.PP
Example #1: Use HTTP package
Example #1: Download a web page
.CS



package require http
package require tls
set url "https://www\&.tcl\&.tk/"

set url "https://www\&.tcl\&.tk/"
http::register https 443 [list ::tls::socket -autoservername 1 -require 1  -command ::tls::callback -password ::tls::password  -validatecommand ::tls::validate_command]
http::register https 443 [list ::tls::socket -autoservername 1 -require 1]

# Check for error
# Get URL
set token [http::geturl $url]

# Check for error
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]
# Save web page to file
set ch [open example\&.html wb]
puts $ch [http::data $token]
close $ch

# Cleanup
::http::cleanup $token

.CE
Example #2: Use raw socket
Example #2: Download a file
.CS



package require tls

set url "www\&.tcl-lang\&.org"
set port 443

set ch [tls::socket -autoservername 1 -servername $url -require 1  -alpn {http/1\&.1} -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

.CE
.SH "HTTP PACKAGE 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, set -cadir or use -cafile as needed\&.
.PP
Example #3: Get web page
.CS



package require http
package require tls
set url "https://www\&.tcl\&.tk/"

http::register https 443 [list ::tls::socket -autoservername 1 -require 1]

# 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

.CE
Example #4: Download file
.CS



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 1 -require 1]

# Open output file
# Get file
set filename [file tail $url]
set ch [open $filename wb]

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

# Check for error
if {[http::status $token] ne "ok"} {
    puts [format "Error %s" [http::status $token]]
}

# Cleanup
close $ch
::http::cleanup $token

.CE
.SH "SPECIAL CONSIDERATIONS"