TclTLS
Check-in [65f827b5f9]
Login
HomeTimelineDownloadBrowse SourceBranchesTagsTicketsWiki
Overview
Comment:Moved debug script examples from docs to demos directory
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk | main
Files: files | file ages | folders
SHA3-256: 65f827b5f9b64872c95d1ce906fed1cc09c1a1a6bd75ee831b57154bba285d2d
User & Date: bohagan on 2025-01-01 23:32:02.000
Other Links: branch diff | manifest | tags
Context
2025-01-02
08:38
Fix source dir path for installing docs when not building in source root check-in: 4056acea19 user: [email protected] tags: trunk, main
2025-01-01
23:32
Moved debug script examples from docs to demos directory check-in: 65f827b5f9 user: bohagan tags: trunk, main
22:38
Added demos directory with example scripts to download web pages and files using TLS. check-in: 0ebb44402a user: bohagan tags: trunk, main
Changes
Unified Diff Ignore Whitespace Patch
Modified demos/README.txt from [f1f90a4669] to [42b678e261].
︙︙
9
10
11
12
13
14
15






16
17
18
19
20
21
22
23
24
25
26
27
28


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.







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








>
>
>
>
>
>





|








9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


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
︙︙
Added demos/gets_with_debug_data.tcl version [960a32efae].
Added demos/http_debug_example.tcl version [751d5e786a].
Modified doc/tls.html from [bfb653d325] to [fdf809c1ad].
︙︙
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

<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="#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>








|
|
<








121
122
123
124
125
126
127
128
129

130
131
132
133
134
135
136

<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">HTTP Package Examples</a></li>
<li class="doctools_section"><a href="#section7">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>
︙︙
757
758
759
760
761
762
763
764


765
766
767
768
769
770
771
772
773
774
775


776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826

827
828
829
830

831
832
833
834
835
836
837
838
839
840
841
842

843
844

845




846
847
848
849
850
851
852
853
854
855
856
857
858

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><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>
<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>
<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
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 $data
# Cleanup
::http::cleanup $token
</pre>
<p>Example #4: Download 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]

# Get file
set ch [open $filename wb]

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




# Cleanup
close $ch
::http::cleanup $token
</pre>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">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>








|
>
>
|
|
|
|



|
<
<
|
>
>
|
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<





|

>



|
>
|
|



|




<

>
|

>

>
>
>
>





|








756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773


774
775
776
777
778










































779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801

802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824

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 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">HTTP Package Examples</a></h2>


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

http::register https 443 [list ::tls::socket -autoservername 1 -require 1]
# Open output 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="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>
︙︙
Modified doc/tls.man from [b593d26bb2] to [741f38b808].
︙︙
845
846
847
848
849
850
851
852


853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879

880
881
882

883
884
885
886
887
888
889
890

891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970

971
972


973





974
975
976
977
978
979
980

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

[para]

[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, specify -cadir or -cafile as needed. See the
demos directory for more elaborate examples.

[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 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 "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: Use raw socket

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


# Get file
set ch [open $filename wb]


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






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

[section "Special Considerations"]








|
>
>
|
|
|
|






|

|
|
|
|



|





<

>
|
|
|
>


<




|
>
|
|





|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







<
<


>
|

>
>

>
>
>
>
>








845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879

880
881
882
883
884
885
886
887

888
889
890
891
892
893
894
895
896
897
898
899
900
901





























































902
903
904
905
906
907
908


909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928

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 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 "HTTP Package 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: Download a 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]

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

# Check for error

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

# Save web page to file
set ch [open example.html wb]
puts $ch [http::data $token]
close $ch

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

Example #2: Download a file






























































[example {

package require http
package require tls

set url "https://wiki.tcl-lang.org/sitemap.xml"


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

# Open output 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"]
︙︙
Modified doc/tls.n from [c33044612f] to [1a60ba709a].
︙︙
1042
1043
1044
1045
1046
1047
1048
1049


1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071

1072
1073
1074
1075


1076
1077
1078
1079
1080

1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158

1159
1160


1161





1162
1163
1164
1165
1166
1167
1168

\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\&.
.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\&.
.PP
Example #1: Use HTTP package
.CS



package require http
package require tls
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]

# 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

.CE
Example #2: Use raw socket
.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]


# Get file
set ch [open $filename wb]


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






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

.CE
.SH "SPECIAL CONSIDERATIONS"








|
>
>
|
|
|
|



|
|
|
|
|

|






<

>
|

|

>
>




|
>
|
|





|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<








<
<


>
|

>
>

>
>
>
>
>








1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071

1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093


























































1094
1095
1096
1097
1098
1099
1100
1101


1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121

\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 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 "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: Download a 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]

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

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

# 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: Download a file


























































.CS



package require http
package require tls

set url "https://wiki\&.tcl-lang\&.org/sitemap\&.xml"


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

# Open output 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"
︙︙
Powered by Fossil · RSS