| ︙ | | |
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
|
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
|
+
+
-
+
+
+
|
<dd><b>tls::unimport</b> <em>channel</em></dd>
<dt> </dt>
<dd><b>tls::ciphers</b> <em>?protocol? ?verbose? ?supported?</em></dd>
<dd><b>tls::protocols</b></dd>
<dd><b>tls::version</b></dd>
</dl></dd>
<dd><a href="#COMMANDS">COMMANDS</a></dd>
<dd><a href="#CERTIFICATE VALIDATION">CERTIFICATE VALIDATION</a></dd>
<dd><a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a></dd>
<dd><a href="#DEBUG">DEBUG</a></dd>
<dd><a href="#HTTPS EXAMPLE">HTTPS EXAMPLE</a></dd>
<dd><a href="#SEE ALSO">SPECIAL CONSIDERATIONS</a></dd>
<dd><a href="#SPECIAL CONSIDERATIONS">SPECIAL CONSIDERATIONS</a></dd>
<dd><a href="#SEE ALSO">SEE ALSO</a></dd>
</dl>
<br>
<hr>
<h3><a name="NAME">NAME</a></h3>
<p><strong>tls</strong> - binding to <strong>OpenSSL</strong> library
for encrypted socket and I/O channel communications.</p>
<br>
<hr>
<h3><a name="SYNOPSIS">SYNOPSIS</a></h3>
<p><b>package require Tcl</b> <em>?<b>8.5-</b>?</em><br>
<b>package require tls</b> <em>?<b>1.8-</b>?</em><br>
|
| ︙ | | |
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
+
+
|
<a href="#tls::import"><b>tls::import</b> <i>channel ?options?</i></a><br>
<a href="#tls::unimport"><b>tls::unimport</b> <i>channel</i></a><br>
<br>
<a href="#tls::ciphers"><b>tls::ciphers</b> <i>?protocol? ?verbose? ?supported?</i></a><br>
<a href="#tls::protocols"><b>tls::protocols</b></a><br>
<a href="#tls::version"><b>tls::version</b></a><br>
</p>
<br>
<hr>
<h3><a name="DESCRIPTION">DESCRIPTION</a></h3>
<p>This extension provides TCL script access to secure socket communications
using the Transport Layer Security (TLS) protocol. It provides a generic
binding to <a href="https://www.openssl.org/">OpenSSL</a>, utilizing the
<strong>Tcl_StackChannel</strong> API in TCL 8.4 and higher.
These sockets behave exactly the same as channels created using the built-in
<strong>socket</strong> command, along with additional options for controlling
the SSL/TLS session.
</p>
<br>
<hr>
<h3><a name="COMMANDS">COMMANDS</a></h3>
<p>Typically one would use the <strong>tls::socket </strong>command
which provides compatibility with the native TCL <strong>socket</strong>
|
| ︙ | | |
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
-
-
+
+
+
-
-
+
+
+
+
-
-
-
-
+
+
+
+
+
+
|
<dt><strong>-alpn</strong> <em>list</em></dt>
<dd>List of protocols to offer during Application-Layer
Protocol Negotiation (ALPN). For example: <em>h2</em> and
<em>http/1.1</em>, but not <em>h3</em> or <em>quic</em>.</dd>
<dt><strong>-cadir</strong> <em>dir</em></dt>
<dd>Specifies the directory where the Certificate Authority (CA)
certificates are stored. The default is platform specific and can be
set at compile time. This can be overridden via the <b>SSL_CERT_DIR</b>
environment variable.</dd>
set at compile time. The default location can be overridden via the
<b>SSL_CERT_DIR</b> environment variable.
See <a href="#CERTIFICATE VALIDATION">CERTIFICATE VALIDATION</a>.</dd>
<dt><strong>-cafile </strong><em>filename</em></dt>
<dd>Specifies the file with the Certificate Authority (CA) certificates
to use. The default is <b>cert.pem</b>, in the OpenSSL directory. This can
also be overridden via the <b>SSL_CERT_FILE</b> environment variable.</dd>
to use. The default is <b>cert.pem</b>, in the OpenSSL directory.
The default file can be overridden via the <b>SSL_CERT_FILE</b>
environment variable.
See <a href="#CERTIFICATE VALIDATION">CERTIFICATE VALIDATION</a>.</dd>
<dt><strong>-castore</strong> <em>URI</em></dt>
<dd>URI for a store, which may be a single container or a catalog of
containers. On Windows, set to "org.openssl.winstore://" to use the
built-in Windows Cert Store. The Windows cert store only supports
root certificate stores.</dd>
<dd>URI for a Certificate Authority (CA) store, which may be a single
container or a catalog of containers. Starting with OpenSSL 3.2 on
Windows, set to "org.openssl.winstore://" to use the built-in
Windows Cert Store. The Windows cert store only supports root
certificate stores.
See <a href="#CERTIFICATE VALIDATION">CERTIFICATE VALIDATION</a>.</dd>
<dt><strong>-certfile</strong> <em>filename</em></dt>
<dd>Specifies the file with the certificate to use in PEM format.
This also contains the public key.</dd>
<dt><strong>-cert</strong> <em>binary_string</em></dt>
<dd>Specifies the certificate to use as a DER encoded string (X.509 DER).</dd>
<dt><strong>-cipher</strong> <em>string</em></dt>
<dd>Specifies the list of ciphers to use for TLS 1.2 and earlier. String is a
|
| ︙ | | |
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
-
+
+
-
-
-
+
+
+
+
|
obtain a password. This is typically used to unlock the private key of
a certificate. The callback should return a password string.
See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a> for more info.</dd>
<dt><strong>-post_handshake</strong> <em>bool</em></dt>
<dd>Allow post-handshake session ticket updates.</dd>
<dt><strong>-request </strong><em>bool</em></dt>
<dd>Request a certificate from peer during the SSL handshake. This is
needed to do certificate validation. (default is <em>true</em>)</dd>
needed to do certificate validation. (default is <em>true</em>).
See <a href="#CERTIFICATE VALIDATION">CERTIFICATE VALIDATION</a>.</dd>
<dt><strong>-require</strong> <em>bool</em></dt>
<dd>Require a valid certificate from peer during SSL handshake. If this
is set to true, then <strong>-request</strong> must also be set to true
and a either a -cadir, -cafile, or platform default must be provided in
order to validate against. (default is <em>false</em>)</dd>
is set to true, then <strong>-request</strong> must also be set to
true and a either a -cadir, -cafile, -castore, or platform default
must be provided in order to validate against. (default is <em>false</em>).
See <a href="#CERTIFICATE VALIDATION">CERTIFICATE VALIDATION</a>.</dd>
<dt><strong>-security_level</strong> <em>integer</em></dt>
<dd>Specifies the security level (value from 0 to 5). The security level
affects the cipher suite encryption algorithms, supported ECC curves,
supported signature algorithms, DH parameter sizes, certificate key
sizes and signature algorithms. The default is 1 prior to OpenSSL 3.2
and 2 thereafter. Level 3 and higher disable support for session
tickets and only accept cipher suites that provide forward secrecy.</dd>
|
| ︙ | | |
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
|
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
+
+
|
<b>ssl2</b>, <b>ssl3</b>, <b>tls1</b>, <b>tls1.1</b>, <b>tls1.2</b>,
and <b>tls1.3</b>. Exact list depends on OpenSSL version and
compile time flags.</dd>
<dt> </dt>
<dt><a name="tls::version"><strong>tls::version</strong></a></dt>
<dd>Returns the OpenSSL version string.</dd>
</dl>
<br>
<hr>
<h3><a name="CERTIFICATE VALIDATION">CERTIFICATE VALIDATION</a></h3>
<p>
By default, a client TLS connection is set to NOT request nor validate the
server certificates. This limitation is due to the lack of a common cross
platform database of Certificate Authority (CA) provided certificates to
validate against. Many Linux systems natively support OpenSSL and thus have
these certificates installed as part of the OS, but MacOS and Windows do not.
In order to use the <b>-require</b> option, one of the following must be true:</p>
<ul>
<li>On Linux and Unix systems with OpenSSL already installed, if the CA
certificates are stored in the standard locations, or the <b>SSL_CERT_DIR</b>
or <b>SSL_CERT_FILE</b> env vars are set, then no other options are needed.</li>
<li>If OpenSSL is not installed in the default location, or when using Mac OS
or Windows and OpenSSL is installed, the <b>SSL_CERT_DIR</b> and/or
<b>SSL_CERT_FILE</b> env vars or the <b>-cadir</b> and/or <b>-cafile</b>
options must be defined.</li>
<li>On Windows, starting in OpenSSL 3.2, it is now possible to access the
built-in Windows Certificate Store from OpenSSL. This can be achieved by
setting the <b>-castore</b> option to "<b>org.openssl.winstore://</b>".</li>
<li>If OpenSSL is not installed, the CA certificates must be downloaded and
installed with the user software. The CURL team makes them available at
<a href="https://curl.se/docs/caextract.html">CA certificates extracted
from Mozilla</a>. Look for the <b>cacert.pem</b> file. You must then either
set the <b>SSL_CERT_DIR</b> and/or <b>SSL_CERT_FILE</b> env vars or the
<b>-cadir</b> or <b>-cafile</b> options must be set to the file's install
location. It is your responsibility to keep this file up to date.</li>
</ul>
<br>
<hr>
<h3><a name="CALLBACK OPTIONS">CALLBACK OPTIONS</a></h3>
<p>
As indicated above, individual channels can be given their own callbacks
to handle intermediate processing by the OpenSSL library, using the
<strong>-command</strong>, <strong>-password</strong>, and
<strong>-validate_command</strong> options passed to either of
<strong>tls::socket</strong> or <strong>tls::import</strong>.
If the callback generates an error, the <b>bgerror</b> command will be
invoked with the error information.
|
| ︙ | | |
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
|
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
|
+
+
+
+
+
+
-
+
-
-
-
+
+
+
-
-
+
+
-
-
-
-
+
+
-
-
|
<p>
<em>
The use of the reference callbacks <strong>tls::callback</strong>,
<strong>tls::password</strong>, and <strong>tls::validate_command</strong>
is not recommended. They may be removed from future releases.
</em>
</p>
<br>
<hr>
<h3><a name="DEBUG">DEBUG</a></h3>
<p>For most debugging needs, the <b>-callback</b> option can be used to provide
sufficient insight and information on the TLS handshake and progress. If further
troubleshooting insight is needed, the compile time option <b>--enable-debug</b>
can be used to get detailed execution flow status.</p>
TLS key logging can be enabled by setting the environment variable
<p>TLS key logging can be enabled by setting the environment variable
<b>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>
The <strong>tls::debug</strong> variable provides some additional
decrypt the data.</p>
<p>The <strong>tls::debug</strong> 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 <strong>tls::callback</strong> to accept the
certificate, even when it is invalid if the <b>tls::validate_command</b>
callback is used for the <b>-validatecommand</b> option.
</p>
callback is used for the <b>-validatecommand</b> option.</p>
<p>
<em>
The use of the variable <strong>tls::debug</strong> is not recommended.
It may be removed from future releases.
</em>
</p>
|
| ︙ | | |
723
724
725
726
727
728
729
730
731
732
733
734
735
736
|
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
|
+
|
array set conn [tls::connection $ch]
array set chan [chan configure $ch]
close $ch
parray status
parray conn
parray chan
</code></pre>
<br>
<hr>
<h3><a name="HTTPS EXAMPLE">HTTPS EXAMPLE</a></h3>
<p>These examples use the default Unix platform SSL certificates. For standard
installations, -cadir and -cafile should not be needed. If your certificates
|
| ︙ | | |
772
773
774
775
776
777
778
779
780
781
782
783
784
785
|
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
|
+
|
set ch [open $filename wb]
set token [::http::geturl $url -blocksize 65536 -channel $ch]
# Cleanup
close $ch
::http::cleanup $token
</code></pre>
<br>
<hr>
<h3><a name="SPECIAL CONSIDERATIONS">SPECIAL CONSIDERATIONS</a></h3>
<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
|
| ︙ | | |