gets_nonblocking_no_variable.tcl
Download a webpage using gets, no variable arg, and non-blocking I/O.

gets_nonblocking_with_variable.tcl
Download a webpage using gets, variable arg, and non-blocking I/O.

gets_with_debug_data.tcl
Download a webpage using gets with additional debug output.

http_debug_example.tcl
Download a webpage using http package with additional debug output.

http_get_file.tcl
Download a webpage using the http package.

http_get_webpage.tcl
Download a file using the http package.
 

http_get_webpage_proxy.tcl
Download a file using the http and autoproxy packages.

read_blocking_webpage.tcl
Download a webpage using read and blocking I/O.

read_nonblocking_webpage.tcl

<ul>
<li class="doctools_subsection"><a href="#subsection4">Values for Command Callback</a></li>
<li class="doctools_subsection"><a href="#subsection5">Values for Password Callback</a></li>
<li class="doctools_subsection"><a href="#subsection6">Values for Validate Command Callback</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Debug</a></li>
<li class="doctools_section"><a href="#section6">Debug Examples</a></li>
<li class="doctools_section"><a href="#section7">HTTP Package Examples</a></li>
<li class="doctools_section"><a href="#section6">HTTP Package Examples</a></li>
<li class="doctools_section"><a href="#section7">Special Considerations</a></li>
<li class="doctools_section"><a href="#section8">Special Considerations</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>

sufficient insight and information on the TLS handshake and progress. If
further troubleshooting insight is needed, the compile time option
<b class="option">--enable-debug</b> can be used to get detailed execution flow status.</p>
<p>TLS key logging can be enabled by setting the environment variable
<b class="variable">SSLKEYLOGFILE</b> 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.</p>
<p>The <b class="variable">tls::debug</b> 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 <b class="cmd">tls::callback</b>
to accept the certificate, even when it is invalid if the
<b class="option">-validatecommand</b> option is set to <b class="cmd">tls::validate_command</b>.</p>
<p>The <b class="variable">tls::debug</b> variable provides some additional control over the
debug logging in the <b class="cmd">tls::callback</b>, <b class="cmd">tls::password</b>, and
<b class="cmd">tls::validate_command</b> default handlers in &quot;<b class="file">tls.tcl</b>&quot;.
The default value is 0 with higher values producing more diagnostic output,
and will also force the verify method in <b class="cmd">tls::callback</b> to accept the
certificate, even if it is invalid when the <b class="option">-validatecommand</b>
option is set to <b class="cmd">tls::validate_command</b>.</p>
<p><em>The use of the variable <b class="variable">tls::debug</b> is not recommended.
It may be removed from future releases.</em></p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Debug Examples</a></h2>
<div id="section6" class="doctools_section"><h2><a name="section6">HTTP Package Examples</a></h2>
<p>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.</p>
<p>Example #1: Use HTTP package</p>
<p>The following are example scripts to download a webpage and file using the
http package. See <span class="sectref"><a href="#section3">Certificate Validation</a></span> for whether the
<b class="option">-cadir</b>, <b class="option">-cafile</b>, and <b class="option">-castore</b> options are also
needed. See the demos directory for more example scripts.</p>
<p>Example #1: Download a web page</p>
<pre class="doctools_example">
package require http
package require tls
set url &quot;https://www.tcl.tk/&quot;
http::register https 443 [list ::tls::socket -autoservername 1 -require 1  -command ::tls::callback -password ::tls::password  -validatecommand ::tls::validate_command]
# Check for error
set token [http::geturl $url]
if {[http::status $token] ne &quot;ok&quot;} {
    puts [format &quot;Error %s&quot; [http::status $token]]
}
# Get web page
set data [http::data $token]
puts [string length $data]
# Cleanup
::http::cleanup $token
</pre>
<p>Example #2: Use raw socket</p>
<pre class="doctools_example">
package require tls
set url &quot;www.tcl-lang.org&quot;
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 &quot;GET / HTTP/1.1&quot;
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
</pre>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">HTTP Package Examples</a></h2>
<p>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.</p>
<p>Example #3: Get web page</p>
<pre class="doctools_example">
package require http
package require tls
set url &quot;https://www.tcl.tk/&quot;
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 &quot;ok&quot;} {
    puts [format &quot;Error %s&quot; [http::status $token]]
}
# Get web page
set data [http::data $token]
puts $data
# Save web page to file
set ch [open example.html wb]
puts $ch [http::data $token]
close $ch
# Cleanup
::http::cleanup $token
</pre>
<p>Example #4: Download file</p>
<p>Example #2: Download a file</p>
<pre class="doctools_example">
package require http
package require tls
set url &quot;https://wiki.tcl-lang.org/sitemap.xml&quot;
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 &quot;ok&quot;} {
    puts [format &quot;Error %s&quot; [http::status $token]]
}
# Cleanup
close $ch
::http::cleanup $token
</pre>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Special Considerations</a></h2>
<div id="section7" class="doctools_section"><h2><a name="section7">Special Considerations</a></h2>
<p>The capabilities of this package can vary enormously based upon how the
linked to OpenSSL library was configured and built. New versions may obsolete
older protocol versions, add or remove ciphers, change default values, etc.
Use the <b class="cmd">tls::protocols</b> commands to obtain the supported
protocol versions.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>

TLS key logging can be enabled by setting the environment variable
[var SSLKEYLOGFILE] 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.

[para]

The [var 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 [cmd tls::callback]
to accept the certificate, even when it is invalid if the
[option -validatecommand] option is set to [cmd tls::validate_command].
The [var tls::debug] variable provides some additional control over the
debug logging in the [cmd tls::callback], [cmd tls::password], and
[cmd tls::validate_command] default handlers in [file tls.tcl].
The default value is 0 with higher values producing more diagnostic output,
and will also force the verify method in [cmd tls::callback] to accept the
certificate, even if it is invalid when the [option -validatecommand]
option is set to [cmd tls::validate_command].

[para]

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

[section "Debug Examples"]
[section "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, specify -cadir or -cafile as needed. See the
demos directory for more elaborate examples.
The following are example scripts to download a webpage and file using the
http package. See [sectref "Certificate Validation"] for whether the
[option -cadir], [option -cafile], and [option -castore] options are also
needed. See the demos directory for more example scripts.

[para]

Example #1: Use HTTP package
Example #1: Download a web page

[example {

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]

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

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

# Cleanup
::http::cleanup $token
}]

Example #2: Use raw socket
Example #2: Download a file

[example {

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

[section "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.

[para]

Example #3: Get web page

[example {

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

Example #4: Download file

[example {

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

[section "Special Considerations"]

\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"