TclTLS
Diff
Login
HomeTimelineDownloadBrowse SourceBranchesTagsTicketsWiki
Annotate Patch Side-by-side Diff

Differences From Artifact [9494c1c42e]:

To Artifact [e059630135]:

︙
27
28
29
30
31
32
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
63
64
65
66

67
68
69














70
71
72
73
74
75
76

27
28
29
30
31
32
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
63
64
65
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
93
94
95
96
97
98
99
100








+
-
+
+
+


+
+
+
+
+
+
+
+
+


















-
+











+
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+








	    <dd><b>tls::socket</b> <em> ?-server command? ?options? port</em></dd>
	    <dd><b>tls::handshake</b> <em> channel</em></dd>
	    <dd><b>tls::status </b> <em>?-local? channel</em></dd>
	    <dd><b>tls::connection </b> <em>channel</em></dd>
	    <dd><b>tls::import</b> <em>channel ?options?</em></dd>
	    <dd><b>tls::unimport</b> <em>channel</em></dd>
	    <dt>&nbsp;</dt>
	    <dd><b>tls::cipher</b> <em>name</em></dd>
	    <dd><b>tls::ciphers </b> <em>protocol ?verbose? ?supported?</em></dd>
	    <dd><b>tls::ciphers</b> <em>?protocol? ?verbose? ?supported?</em></dd>
	    <dd><b>tls::digests</b> <em>?name?</em></dd>
	    <dd><b>tls::macs</b></dd>
	    <dd><b>tls::protocols</b></dd>
	    <dd><b>tls::version</b></dd>
	    <dt>&nbsp;</dt>
	    <dd><b>tls::digest</b> <b>-digest</b> <em>name ?options?</em></dd>
	    <dd><b>tls::cmac</b> <b>-cipher</b> <em>name</em> <b>-key</b> <em>key ?options?</em></dd>
	    <dd><b>tls::hmac</b> <b>-digest</b> <em>name</em> <b>-key</b> <em>key ?options?</em></dd>
	    <dd><b>tls::md4</b> <em>data</em></dd>
	    <dd><b>tls::md5</b> <em>data</em></dd>
	    <dd><b>tls::sha1</b> <em>data</em></dd>
	    <dd><b>tls::sha256</b> <em>data</em></dd>
	    <dd><b>tls::sha512</b> <em>data</em></dd>
	</dl>
    </dd>
    <dd><a href="#COMMANDS">COMMANDS</a></dd>
    <dd><a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a></dd>
    <dd><a href="#HTTPS EXAMPLE">HTTPS EXAMPLE</a></dd>
    <dd><a href="#SEE ALSO">SPECIAL CONSIDERATIONS</a></dd>
    <dd><a href="#SEE ALSO">SEE ALSO</a></dd>
</dl>

<hr>

<h3><a name="NAME">NAME</a></h3>

<p><strong>tls</strong> - binding to <strong>OpenSSL</strong>
toolkit.</p>

<h3><a name="SYNOPSIS">SYNOPSIS</a></h3>

<p><b>package require Tcl 8.4</b><br>
<p><b>package require Tcl 8.5</b><br>
<b>package require tls</b><br>
<br>
<a href="#tls::init"><b>tls::init</b> <i>?options?</i></a><br>
<a href="#tls::socket"><b>tls::socket</b> <i>?options? host port</i><br>
<a href="#tls::socket"><b>tls::socket</b> <i>?-server command? ?options? port</i></a><br>
<a href="#tls::status"><b>tls::status</b> <i>?-local? channel</i></a><br>
<a href="#tls::connection"><b>tls::connection</b> <i>channel</i></a><br>
<a href="#tls::handshake"><b>tls::handshake</b> <i>channel</i></a><br>
<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::cipher"><b>tls::cipher</b> <i>name</i></a><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>
<a href="#tls::version"><b>tls::version</b></a>
<a href="#tls::ciphers"><b>tls::ciphers</b> <i>?protocol? ?verbose? ?supported?</i></a><br>
<a href="#tls::digests"><b>tls::digests</b> <i>?name?</i></a><br>
<a href="#tls::macs"><b>tls::macs</b></a><br>
<a href="#tls::protocols"><b>tls::protocols</b></a><br>
<a href="#tls::version"><b>tls::version</b></a><br>
<br>
<a href="#tls::digest"><b>tls::digest</b> <b>-digest</b> <i>name ?options?</i></a><br>
<a href="#tls::cmac"><b>tls::cmac</b> <b>-cipher</b> <i>name</i> <b>-key</b> <i>key ?options?</i></a><br>
<a href="#tls::hmac"><b>tls::hmac</b> <b>-digest</b> <i>name</i> <b>-key</b> <i>key ?options?</i></a><br>
<a href="#tls::md4"><b>tls::md4</b> <i>data</i></a><br>
<a href="#tls::md5"><b>tls::md5</b> <i>data</i></a><br>
<a href="#tls::sha1"><b>tls::sha1</b> <i>data</i></a><br>
<a href="#tls::sha256"><b>tls::sha256</b> <i>data</i></a><br>
<a href="#tls::sha512"><b>tls::sha512</b> <i>data</i></a><br>
</p>

<h3><a name="DESCRIPTION">DESCRIPTION</a></h3>

<p>This extension provides a generic binding to <a
href="http://www.openssl.org/">OpenSSL</a>, utilizing the
<strong>Tcl_StackChannel</strong>
︙
99
100
101
102
103
104
105
106

107
108
109
110
111
112
113

123
124
125
126
127
128
129

130
131
132
133
134
135
136
137








-
+








	host port</em></a></dt>
    <dt><b>tls::socket</b><em> ?-server command? ?options? port</em></dt>
    <dd>This is a helper function that utilizes the underlying
	commands (<strong>tls::import</strong>). It behaves
	exactly the same as the native Tcl <strong>socket</strong>
	command except that the options can include any of the
	applicable <a href="#tls::import"><strong>tls:import</strong></a>
	options with one additional option:
	options with one additional option:</dd>
<blockquote>
    <dl>
	<dt><strong>-autoservername</strong> <em>bool</em></dt>
	<dd>Automatically send the -servername as the <em>host</em> argument
	    (default is <em>false</em>)</dd>
    </dl>
</blockquote>
︙
179
180
181
182
183
184
185
186

187
188
189
190
191
192
193

203
204
205
206
207
208
209

210
211
212
213
214
215
216
217








-
+








	<dt><strong>-request </strong><em>bool</em></dt>
	<dd>Request a certificate from peer during SSL handshake.
	    (default is <em>true</em>)</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. (default is <em>false</em>)</dd>
	<dt><strong>-securitylevel</strong> <em>integer</em></dt>
	<dt><strong>-security_level</strong> <em>integer</em></dt>
	<dd>Set security level. Must be 0 to 5. The security level affects
	    cipher suite encryption algorithms, supported ECC curves,
	    supported signature algorithms, DH parameter sizes, certificate
	    key sizes and signature algorithms. The default is 1.
	    Level 3 and higher disable support for session tickets and only
	    accept cipher suites that provide forward secrecy.</dd>
	<dt><strong>-server</strong> <em>bool</em></dt>
︙
228
229
230
231
232
233
234
235

236
237
238
239


240
241
242
243
244
245
246

252
253
254
255
256
257
258

259
260
261


262
263
264
265
266
267
268
269
270








-
+


-
-
+
+








    <dt><a name="tls::handshake"><strong>tls::handshake</strong> <em>channel</em></a></dt>
    <dd>Forces handshake to take place, and returns 0 if
	handshake is still in progress (non-blocking), or 1 if
	the handshake was successful. If the handshake failed
	this routine will throw an error.</dd>
    <dt>&nbsp;</dt>
    <dt><a name="tls::status"><strong>tls::status</strong>
    <em>?-local? channel</em></a></dt>
    <em>?</em><b>-local</b><em>? channel</em></a></dt>
    <dd>Returns the current status of the certificate for an SSL
	channel. The result is a list of key-value pairs describing
	the certificate. If the result is an empty list then the
	SSL handshake has not yet completed. If <em>-local</em> is
	the certificate. If the SSL handshake has not yet completed,
	an empty list is returned. If <b>-local</b> is
	specified, then the local certificate is used.</dd>
<blockquote>
	<b>SSL Status</b>
    <dl>
	<dt><strong>alpn</strong> <em>protocol</em></dt>
	<dd>The protocol selected after Application-Layer Protocol
	    Negotiation (ALPN).</dd>
︙
350
351
352
353
354
355
356
357

358
359

360
361
362
363
364
365
366
367
368


369
370
371
372
373
374
375
376
377
378

379
380
381
382
383



384

385
386
387


388
389
390
391
392
393
394

374
375
376
377
378
379
380

381
382

383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403

404
405
406
407
408
409
410
411
412

413
414
415
416
417
418
419
420
421
422
423
424
425








-
+

-
+









+
+









-
+





+
+
+
-
+



+
+








	<dt><strong>state</strong> <em>state</em></dt>
	<dd>State of the connection.</dd>
	<dt><strong>servername</strong> <em>name</em></dt>
	<dd>The name of the connected to server.</dd>
	<dt><strong>protocol</strong> <em>version</em></dt>
	<dd>The protocol version used for the connection:
	    SSL2, SSL3, TLS1, TLS1.1, TLS1.2, TLS1.3, or unknown.</dd>
	<dt><strong>renegotiation</strong> <em>boolean</em></dt>
	<dt><strong>renegotiation_allowed</strong> <em>boolean</em></dt>
	<dd>Whether protocol renegotiation is supported or not.</dd>
	<dt><strong>securitylevel</strong> <em>level</em></dt>
	<dt><strong>security_level</strong> <em>level</em></dt>
	<dd>The security level used for selection of ciphers, key size, etc.</dd>
	<dt><strong>session_reused</strong> <em>boolean</em></dt>
	<dd>Whether the session has been reused or not.</dd>
	<dt><strong>is_server</strong> <em>boolean</em></dt>
	<dd>Whether the connection is configured as a server (1) or client (0).</dd>
	<dt><strong>compression</strong> <em>mode</em></dt>
	<dd>Compression method.</dd>
	<dt><strong>expansion</strong> <em>mode</em></dt>
	<dd>Expansion method.</dd>
	<dt><strong>caList</strong> <em>list</em></dt>
	<dd>List of Certificate Authorities (CA) for X.509 certificate.</dd>
    </dl>
</blockquote>
<blockquote>
	<b>Cipher Info</b>
    <dl>
	<dt><strong>cipher</strong> <em>cipher</em></dt>
	<dd>The current cipher in use for the connection.</dd>
	<dt><strong>standard_name</strong> <em>name</em></dt>
	<dd>The standard RFC name of cipher.</dd>
	<dt><strong>bits</strong> <em>n</em></dt>
	<dt><strong>algorithm_bits</strong> <em>n</em></dt>
	<dd>The number of processed bits used for cipher.</dd>
	<dt><strong>secret_bits</strong> <em>n</em></dt>
	<dd>The number of secret bits used for cipher.</dd>
	<dt><strong>min_version</strong> <em>version</em></dt>
	<dd>The minimum protocol version for cipher.</dd>
	<dt><strong>cipher_is_aead</strong> <em>boolean</em></dt>
	<dd>Whether the cipher is Authenticated encryption with associated
	data (AEAD).</dd>
	<dt><strong>id</strong> <em>id</em></dt>
	<dt><strong>cipher_id</strong> <em>id</em></dt>
	<dd>The OpenSSL cipher id.</dd>
	<dt><strong>description</strong> <em>string</em></dt>
	<dd>A text description of the cipher.</dd>
	<dt><strong>handshake_digest</strong> <em>boolean</em></dt>
	<dd>Digest used during handshake.</dd>
    </dl>
</blockquote>
<blockquote>
	<b>Session Info</b>
    <dl>
	<dt><strong>alpn</strong> <em>protocol</em></dt>
	<dd>The protocol selected after Application-Layer Protocol
︙
409
410
411
412
413
414
415
416





417
418
419
420




421
422
423
424
425














426
427
428
429
430
431
432
433
434




















































































435
436
437
438
439
440
441

440
441
442
443
444
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
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571









+
+
+
+
+

-
-
-
+
+
+
+
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+









+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+








	<dd>Unique session ticket application data.</dd>
	<dt><strong>master_key</strong> <em>binary_string</em></dt>
	<dd>Unique session master key.</dd>
	<dt><strong>session_cache_mode</strong> <em>mode</em></dt>
	<dd>Server cache mode (client, server, or both).</dd>
    </dl>
</blockquote>

    <dt><a name="tls::cipher"><strong>tls::cipher</strong> <em>name</em></a></dt>
    <dd>Return a list of property names and values describing cipher
	<i>name</i>. Properties include name, description, block_size,
	key_length, iv_length, type, and mode list.</dd>

    <dt><a name="tls::ciphers"><strong>tls::ciphers</strong>
    <em>protocol ?verbose? ?supported?</em></a></dt>
    <dd>Returns a list of supported ciphers available for <em>protocol</em>,
	where protocol must be one of <b>ssl2, ssl3, tls1, tls1.1,
    <em>?protocol? ?verbose? ?supported?</em></a></dt>
    <dd>Without any args, returns a list of all ciphers. With <em>protocol</em>,
	only the ciphers supported for that protocol are returned. See
	<b>tls::protocols</b> command for the supported protocols. If
	tls1.2,</b> or <b>tls1.3</b>. If <em>verbose</em> is specified as
	true then a verbose, human readable list is returned with
	additional information on the cipher. If <em>supported</em>
	is specified as true, then only the ciphers supported for protocol
	will be listed.</dd>
	<em>verbose</em> is specified as true then a verbose, human readable
	list is returned with additional information on the cipher. If
	<em>supported</em> is specified as true, then only the ciphers
	supported for protocol will be listed.</dd>

    <dt><a name="tls::digests"><strong>tls::digests</strong> <em>?name?</em></a></dt>
    <dd>Without <em>name</em>, returns a list of the supported hash algorithms
	for <b>tls::digest</b> command. With <em>name</em>, returns a list of
	property names and values describing digest <i>name</i>. Properties
	include name, description, size, block_size, type, and flags list.</dd>

    <dt><a name="tls::macs"><strong>tls::macs</strong></a></dt>
    <dd>Returns a list of the available Message Authentication Codes (MAC) for
	the <b>tls::digest</b> command.</dd>

    <dt><a name="tls::protocols"><strong>tls::protocols</strong></a></dt>
    <dd>Returns a list of supported protocols. Valid values are:
	<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><a name="tls::version"><strong>tls::version</strong></a></dt>
    <dd>Returns the OpenSSL version string.</dd>

    <br>
    <dt><a name="tls::digest"><strong>tls::digest</strong> <b>-digest</b>
	<em>name ?</em><b>-bin</b>|<b>-hex</b><em>? [</em><b>-file</b> <em>filename | </em><b>-command</b> <em>cmdName |
	</em><b>-chan</b> <em>channelId | </em><b>-data</b> <em>data]</em></a></dt>
    <dd>Calculate the message digest (MD) of data using <em>name</em> hash
	function and return the resulting hash value as a hex string (default)
	or as a binary value with <b>-bin</b> or <b>-binary</b> option. MDs
	are used to ensure the integrity of data. The hash function can be any
	supported OpenSSL algorithm such as <b>md4</b>, <b>md5</b>, <b>sha1</b>,
	<b>sha256</b>, <b>sha512</b>, <b>sha3-256</b>, etc. See
	<b>tls::digests</b> command for a full list. In OpenSSL 3.0+, older
	algorithms may reside in the legacy provider.
	<br>
	Using the <b>-data</b> option will immediately return the message
	digest for <em>data</em> in the specified format. Example code:
<blockquote><code>
		set md [::tls::digest sha256 "Some example data."]<br>
</code></blockquote>
	Using the <b>-file</b> or <b>-filename</b> option will open file
	<em>filename</em>, read the file data, close the file, and return the
	message digest in the specified format. This uses the TCL APIs, so VFS
	files are supported. Example code:
<blockquote><code>
		set md [::tls::digest -digest sha256 -file test_file.txt]<br>
</code></blockquote>
	Using the <b>-chan</b> or <b>-channel</b> option, a stacked channel is
	created for <em>channelId</em> and data read from the channel is used
	to calculate a message digest with the result returned with the last
	read operation before EOF. Channel is automatically set to binary mode.
	Example code:
<blockquote><code>
		set ch [open test_file.txt r]<br>
		::tls::digest -digest sha256 -chan $ch<br>
		while {![eof $ch]} {set md [read $ch 4096]}<br>
		close $ch
</code></blockquote>
	Using the <b>-command</b> option, a new command <em>cmdName</em> is
	created and returned. To add data to the hash function, call
	&quot;<em>cmdName</em> <b>update</b> <em>data</em>&quot;, where data is
	the data to add. When done, call &quot;<em>cmdName</em> <b>finalize</b>&quot;
	to return the message digest. Example code:
<blockquote><code>
		set cmd [::tls::digest -digest sha256 -command ::tls::temp]<br>
		$cmd update "Some data. "<br>
		$cmd update "More data."<br>
		set md [$cmd finalize]
</code></blockquote>
	</dd>

    <dt><a name="tls::cmac"><strong>tls::cmac</strong> <b>-cipher</b> <em>name</em>
	<b>-key</b> <em>key ?</em><b>-bin</b>|<b>-hex</b><em>? [</em><b>-file</b> <em>filename | </em><b>-command</b> <em>cmdName |
	</em><b>-chan</b> <em>channelId | </em><b>-data</b> <em>data]</em></a></dt>
    <dd>Calculate the Cipher-based Message Authentication Code (CMAC). MACs
	are used to ensure authenticity and the integrity of data. It uses the
	same options as <b>tls::digest</b>, plus the additional option
	<b>-cipher</b> to specify the cipher to use and for certain ciphers,
	<b>-key</b> to specify the key.</dd>

    <dt><a name="tls::hmac"><strong>tls::hmac</strong> <b>-digest</b> <em>name</em>
	<b>-key</b> <em>key ?</em><b>-bin</b>|<b>-hex</b><em>? [</em><b>-file</b> <em>filename | </em><b>-command</b> <em>cmdName |
	</em><b>-chan</b> <em>channelId | </em><b>-data</b> <em>data]</em></a></dt>
    <dd>Calculate the Hash-based Message Authentication Code (HMAC). HMACs are
	used to ensure the data integrity and authenticity of a message using a
	shared secret key. The cryptographic strength depends upon the size of
	the key and the security of the hash function used. It uses the same
	options as <b>tls::digest</b>, plus additional option <b>-key</b> to
	specify the key to use. To salt a password, append or prepend the salt
	data to the password.</dd>

    <dt><a name="tls::md4"><strong>tls::md4</strong> <em>data</em></a></dt>
    <dd>Returns the MD4 message-digest for <em>data</em> as a hex string.</dd>

    <dt><a name="tls::md5"><strong>tls::md5</strong> <em>data</em></a></dt>
    <dd>Returns the MD5 message-digest for <em>data</em> as a hex string.</dd>

    <dt><a name="tls::sha1"><strong>tls::sha1</strong> <em>data</em></a></dt>
    <dd>Returns the SHA1 secure hash algorithm digest for <em>data</em> as a hex string.</dd>

    <dt><a name="tls::sha256"><strong>tls::sha256</strong> <em>data</em></a></dt>
    <dd>Returns the SHA-2 SHA256 secure hash algorithm digest for <em>data</em> as a hex string.</dd>

    <dt><a name="tls::sha512"><strong>tls::sha512</strong> <em>data</em></a></dt>
    <dd>Returns the SHA-2 SHA512 secure hash algorithm digest for <em>data</em> as a hex string.</dd>
</dl>

<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
︙
Powered by Fossil · RSS