1
2
3
4
5
6
7
8
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
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
|
1
2
3
4
5
6
7
8
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
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
|
-
-
-
-
+
+
-
+
+
+
-
+
+
-
+
+
-
+
-
+
-
-
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
|
<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
<title>TLS (SSL) Tcl Commands</title>
<title>TLS (SSL) TCL Commands</title>
<link rel="stylesheet" href="docs.css" type="text/css" media="all">
</head>
<body class="vsc-initialized">
<body bgcolor="#FFFFFF">
<dd><b>tls</b> - binding to <b>OpenSSL</b> toolkit.</dd>
<dd><b>tls</b> - binding to <b>OpenSSL</b> library
for socket and I/O channel communications.</dd>
</dl>
</dd>
<dd><a href="#SYNOPSIS">SYNOPSIS</a> </dd>
<dd><dl>
<dd><b>package require Tcl</b> <em>?8.4?</em></dd>
<dd><b>package require Tcl</b> <em>?8.5?</em></dd>
<dd><b>package require tls</b></dd>
<dt> </dt>
<dd><b>tls::init</b> <em>?options?</em> </dd>
<dd><b>tls::socket</b> <em>?options? host port</em></dd>
<dd><b>tls::socket</b> <em> ?-server command? ?options? port</em></dd>
<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::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>
<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>
<p><strong>tls</strong> - binding to <strong>OpenSSL</strong>
toolkit.</p>
<p><strong>tls</strong> - binding to <strong>OpenSSL</strong> library
for socket and I/O channel communications.</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>
<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>
|
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
-
+
-
+
-
-
+
+
+
+
-
+
-
+
+
-
-
+
+
-
+
-
-
-
+
+
+
-
+
-
+
-
+
+
-
-
-
-
-
+
+
+
+
+
-
+
-
|
<dt><strong>-certfile</strong> <em>filename</em></dt>
<dd>Specify the filename with the certificate to use.</dd>
<dt><strong>-cert</strong> <em>filename</em></dt>
<dd>Specify the contents of a certificate to use, as a DER
encoded binary value (X.509 DER).</dd>
<dt><strong>-cipher</strong> <em>string</em></dt>
<dd>List of ciphers to use. String is a colon (":") separated list
of ciphers or cipher suites. Cipher suites can be combined
of ciphers. Ciphers can be combined
using the <b>+</b> character. Prefixes can be used to permanently
remove ("!"), delete ("-"), or move a cypher to the end of
the list ("+"). Keywords <b>@STRENGTH</b> (sort by algorithm
key length), <b>@SECLEVEL=</b><i>n</i> (set security level to
n), and <b>DEFAULT</b> (use default cipher list, at start only)
can also be specified. See OpenSSL documentation for the full
list of valid values. (TLS 1.2 and earlier only)</dd>
<dt><strong>-ciphersuites</strong> <em>string</em></dt>
<dd>List of cipher suites to use. String is a colon (":")
separated list of cipher suite names. (TLS 1.3 only)</dd>
<dt><strong>-command</strong> <em>callback</em></dt>
<dd>Callback to invoke at several points during the handshake.
<dd>Callback command to invoke at several points during the handshake.
This is used to pass errors and tracing information, and
it can allow Tcl scripts to perform their own certificate
validation in place of the default validation provided by
OpenSSL. See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a>
for further discussion.</dd>
<dt><strong>-dhparams </strong><em>filename</em></dt>
<dd>Specify the Diffie-Hellman parameters file.</dd>
<dt><strong>-keyfile</strong> <em>filename</em></dt>
<dd>Specify the private key file. (default is
value of -certfile)</dd>
<dt><strong>-key</strong> <em>filename</em></dt>
<dd>Specify the private key to use as a DER encoded value (PKCS#1 DER)</dd>
<dt><strong>-model</strong> <em>channel</em></dt>
<dd>Force this channel to share the same <em><strong>SSL_CTX</strong></em>
structure as the specified <em>channel</em>, and
therefore share callbacks etc.</dd>
<dt><strong>-password</strong> <em>callback</em></dt>
<dd>Callback to invoke when OpenSSL needs to obtain a password,
typically to unlock the private key of a certificate. The
<dd>Callback command to invoke when OpenSSL needs to obtain a password.
Typically used to unlock the private key of a certificate. The
callback should return a string which represents the password
to be used. See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a>
for further discussion.</dd>
<dt><strong>-post_handshake</strong> <em>bool</em></dt>
<dd>Allow post-handshake ticket updates.</dd>
<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 and a either a -cadir, -cafile, or platform
default must be provided in order to validate against.
also be set to true. (default is <em>false</em>)</dd>
(default is <em>false</em>)</dd>
<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,
the 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>
<dd>Set to act as a server and respond with a server handshake when
<dd>Handshake as server if true, else handshake as
client. (default is <em>false</em>)</dd>
a client connects and provides a client handshake.
(default is <em>false</em>)</dd>
<dt><strong>-servername</strong> <em>host</em></dt>
<dd>Specify server hostname. Only available if the OpenSSL library
<dd>Specify server's hostname. Used to set the TLS 'Server Name
the package is linked against supports the TLS hostname extension
for 'Server Name Indication' (SNI). Use to name the logical host
we are talking to and expecting a certificate for.</dd>
<dd>Callback to invoke to verify or validate protocol config
<dd>Callback command to invoke to verify or validate protocol config
parameters during the protocol negotiation phase. See
<a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a>
for further discussion.</dd>
</dl>
</blockquote>
<dt><a name="tls::unimport"><b>tls::unimport </b><i>channel</i></a></dt>
<dd>Provided for symmetry to <strong>tls::import</strong>, this
unstacks the SSL-enabling of a regular Tcl channel. An error
unstacks the encryption of a regular Tcl channel. An error
is thrown if TLS is not the top stacked channel type.</dd>
<dt> </dt>
<dt><a name="tls::handshake"><strong>tls::handshake</strong> <em>channel</em></a></dt>
<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> </dt>
<dt><a name="tls::status"><strong>tls::status</strong>
<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 SSL handshake has not yet completed,
an empty list is returned. If <b>-local</b> is
specified, then the local certificate is used.</dd>
<dd>Returns the current status of an SSL channel. The result is a list
of key-value pairs describing the SSL, certificate, and certificate
verification status. 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>
<dt><strong>cipher</strong> <em>cipher</em></dt>
<dd>The current cipher in use between the client and
<dd>The current cipher in use between for the channel.</dd>
server channels.</dd>
|
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
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
|
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
|
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
|
<dt><strong>num_extensions</strong> <em>n</em></dt>
<dd>Number of certificate extensions.</dd>
<dt><strong>extensions</strong> <em>list</em></dt>
<dd>List of certificate extension names.</dd>
<dt><strong>authorityKeyIdentifier</strong> <em>string</em></dt>
<dd>(AKI) Key identifier of the Issuing CA certificate that signed
the SSL certificate as hex string. This value matches the SKI
the SSL certificate as a hex string. This value matches the SKI
value of the Intermediate CA certificate.</dd>
<dt><strong>subjectKeyIdentifier</strong> <em>string</em></dt>
<dd>(SKI) Hash of the public key inside the certificate as hex
<dd>(SKI) Hash of the public key inside the certificate as a hex
string. Used to identify certificates that contain a particular
public key.</dd>
<dt><strong>subjectAltName</strong> <em>list</em></dt>
<dd>List of all of the alternative domain names, sub domains,
and IP addresses that are secured by the certificate.</dd>
<dt><strong>ocsp</strong> <em>list</em></dt>
<dd>List of all Online Certificate Status Protocol (OCSP) URLs.</dd>
<dt><strong>certificate</strong> <em>cert</em></dt>
<dd>The PEM encoded certificate.</dd>
<dt><strong>signatureAlgorithm</strong> <em>algorithm</em></dt>
<dd>Cipher algorithm used for certificate signature.</dd>
<dd>Cipher algorithm used for the certificate signature.</dd>
<dt><strong>signatureValue</strong> <em>string</em></dt>
<dd>Certificate signature as hex string.</dd>
<dd>Certificate signature as a hex string.</dd>
<dt><strong>signatureDigest</strong> <em>version</em></dt>
<dd>Certificate signing digest.</dd>
<dd>Certificate signing digest as a hex string.</dd>
<dt><strong>publicKeyAlgorithm</strong> <em>algorithm</em></dt>
<dd>Certificate signature public key algorithm.</dd>
<dt><strong>publicKey</strong> <em>string</em></dt>
<dd>Certificate signature public key as hex string.</dd>
<dd>Certificate signature public key as a hex string.</dd>
<dt><strong>bits</strong> <em>n</em></dt>
<dd>Number of bits used for certificate signature key</dd>
<dd>Number of bits used for certificate signature key.</dd>
<dt><strong>self_signed</strong> <em>boolean</em></dt>
<dd>Is certificate signature self signed.</dd>
<dd>Whether the certificate signature is self signed.</dd>
<dt><strong>sha1_hash</strong> <em>hash</em></dt>
<dd>The SHA1 hash of the certificate as hex string.</dd>
<dd>The SHA1 hash of the certificate as a hex string.</dd>
<dt><strong>sha256_hash</strong> <em>hash</em></dt>
<dd>The SHA256 hash of the certificate as hex string.</dd>
<dd>The SHA256 hash of the certificate as a hex string.</dd>
</dl>
</blockquote>
<dt><a name="tls::connection"><strong>tls::connection</strong>
<em>channel</em></a></dt>
<dd>Returns the current connection status of an SSL channel. The
result is a list of key-value pairs describing the
result is a list of key-value pairs describing the connection.</dd>
connected peer.</dd>
|
404
405
406
407
408
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
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
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
|
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
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
|
-
-
+
+
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
|
<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>
<dd>Whether the cipher is Authenticated Encryption with
Associated Data (AEAD).</dd>
<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
Negotiation (ALPN).</dd>
<dt><strong>resumable</strong> <em>boolean</em></dt>
<dd>Can the session be resumed or not.</dd>
<dd>Whether the session can be resumed or not.</dd>
<dt><strong>start_time</strong> <em>seconds</em></dt>
<dd>Time since session started in seconds since epoch.</dd>
<dt><strong>timeout</strong> <em>seconds</em></dt>
<dd>Max duration of session in seconds before time-out.</dd>
<dt><strong>lifetime</strong> <em>seconds</em></dt>
<dd>Session ticket lifetime hint in seconds.</dd>
<dt><strong>session_id</strong> <em>binary_string</em></dt>
<dd>Unique session id for use in resuming the session.</dd>
<dt><strong>session_ticket</strong> <em>binary_string</em></dt>
<dd>Unique session ticket for use in resuming the session.</dd>
<dt><strong>ticket_app_data</strong> <em>binary_string</em></dt>
<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>
<dd>Returns a list of supported protocols. Valid values are:
<dd>Returns a list of the 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
"<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. 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::mac"><strong>tls::mac</strong> <b>-cipher</b> <em>name</em>
<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>(OpenSSL 3.0+) Calculate the Message Authentication Code (MAC). MACs
are used to ensure authenticity and the integrity of data. It uses the
same options as <b>tls::digest</b>, plus the additional options
<b>-cipher</b> to specify the cipher to use, <b>-digest</b> to specify
the digest, and for certain ciphers, <b>-key</b> to specify the key.</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>
If the callback generates an error, the <b>bgerror</b> command with be
If the callback generates an error, the <b>bgerror</b> command will be
invoked with the error information.
</p>
<blockquote>
<dl>
<dt><strong>-command</strong> <em>callback</em></dt>
|
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
|
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
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
|
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
+
+
+
+
+
|
internally. The default behavior when the <strong>-password</strong> option is not
specified is for TLS to process the associated library callbacks by attempting
to call <strong>tls::password</strong>.
The difference between these two behaviors is a consequence of maintaining
compatibility with earlier implementations.
</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.
</p>
<p>
<em>
The use of the variable <strong>tls::debug</strong> is not recommended.
It may be removed from future releases.
</em>
</p>
<p>The capabilities of this package can vary enormously based upon how your
OpenSSL library was configured and built. New versions may obsolete older
protocol versions, add or remove ciphers, change default values, etc. Use the
<strong>tls::ciphers</strong> and <strong>tls::protocols</strong> commands to
obtain the supported versions.</p>
<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 <strong>tls::protocols</strong> commands to obtain the supported
protocol versions.</p>
<h3><a name="SEE ALSO">SEE ALSO</a></h3>
<p><strong>socket</strong>, <strong>fileevent, </strong><a
href="http://www.openssl.org/"><strong>OpenSSL</strong></a></p>
<hr>
|