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
|
-
+
+
+
+
+
+
+
+
+
+
+
+
-
+
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|
<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> </dt>
<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></dd>
<dd><b>tls::macs</b></dd>
<dd><b>tls::protocols</b></dd>
<dd><b>tls::version</b></dd>
<dt> </dt>
<dd><b>tls::digest</b> <em>type ?options?</em></dd>
<dd><b>tls::cmac</b> <em>type</em> <b>-cipher</b> <em>name ?options?</em></dd>
<dd><b>tls::hmac</b> <em>type</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::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></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> <i>type ?options?</i></a><br>
<a href="#tls::cmac"><b>tls::cmac</b> <i>type</i> <b>-cipher</b> <i>name ?options?</i></a><br>
<a href="#tls::hmac"><b>tls::hmac</b> <i>type</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>
|
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
|
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
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
|
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|
<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::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,
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>
<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 where <em>protocol</em> must be one of <b>ssl2, ssl3,
tls1, tls1.1, 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>
<dt><a name="tls::digests"><strong>tls::digests</strong></a></dt>
<dd>Returns a list of the hash algorithms for <b>tls::digest</b> command.</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> <em>digest ?-bin|-hex?
[-file filename | -command cmdName | -chan channelId | ?-data? data]</em></a></dt>
<dd>Calculate the message digest for data using <em>digest</em> hash
function. Returns value as a hex string (default) or as a binary value
with <b>-bin</b> option. Argument <em>digest</em> can be any OpenSSL
supported hash function including: <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.
<br>
Using the <b>-data</b> option will immediately return the message
digest for <em>data</em> in the specified format.
<br>
Using the <b>-file</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.
<br>
Using the <b>-chan</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.
<br>
Using the <b>-command</b> option, a new command <em>cmdName</em> is
created and returned. To add data to the hash function, call
"<em>cmdName</em> <b>update</b> <em>data</em>", where data is
the data to add. When done, call "<em>cmdName</em> <b>finalize</b>"
to return the message digest.
</dd>
<dt><a name="tls::cmac"><strong>tls::cmac</strong> <em>digest</em>
<strong>-cipher</strong> <em>name</em> ?-bin|-hex? [-file filename |
-command cmdName | -chan channelId | ?-data? data]</em></a></dt>
<dd>Calculate the Cipher-based Message Authentication Code (CMAC). Same arguments
as <b>tls::digest</b> with 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> <em>digest</em>
<strong>-key</strong> <em>key</em> ?-bin|-hex? [-file filename |
-command cmdName | -chan channelId | ?-data? data]</em></a></dt>
<dd>Calculate the Hashed Message Authentication Code (HMAC). Same arguments
as <b>tls::digest</b> with 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
|