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
|
<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::protocols</b></dd>
<dd><b>tls::version</b></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>
<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>
</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>
|
>
|
>
>
>
>
>
>
>
>
>
>
>
|
>
|
>
>
|
|
>
>
>
>
>
>
>
>
>
|
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> </dt>
<dd><b>tls::cipher</b> <em>name</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> </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.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::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>
|
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
|
<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::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>
is specified as true, then only the ciphers supported for protocol
will be listed.</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>
</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
|
>
>
>
>
>
|
|
>
|
<
|
|
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
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
531
532
533
534
535
536
537
538
539
540
541
|
<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>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
<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 ?-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> or <b>-binary</b> option. Digest 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> 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.
<br>
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.
<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> <b>-cipher</b> <em>name</em>
<b>-key</b> <em>key ?-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> <b>-digest</b> <em>name</em>
<b>-key</b> <em>key ?-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
|