TclTLS
Check-in [c7828a9fcc]
Login
HomeTimelineDownloadBrowse SourceBranchesTagsTicketsWiki
Overview
Comment:Better grouped status and connection parameters in doc.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | status_x509
Files: files | file ages | folders
SHA3-256: c7828a9fcc59b276dab1e1bec61135e890d9a6f9768ab0cfada04605444047a5
User & Date: bohagan on 2023-07-15 21:37:31
Other Links: branch diff | manifest | tags
Context
2023-07-15
23:00
Added unique ids and signature value to status check-in: 8e446cb0bb user: bohagan tags: status_x509
21:37
Better grouped status and connection parameters in doc. check-in: c7828a9fcc user: bohagan tags: status_x509
20:47
Refactored convert X509 status binary values to hex strings. Renamed X509 parameter signatureAlgorithm to signature and digest to signingDigest. check-in: 8dd96d8c7b user: bohagan tags: status_x509
Changes
Unified Diff Ignore Whitespace Patch
Modified doc/tls.html from [aa1cd06cde] to [5abce369e5]. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

16
17
18
19
20
21
22

<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN"> 

<html>

<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Copyright" content="1999 Matt Newman / 2004 Starfish Systems">
<title>TLS (SSL) Tcl Commands</title>
</head>

<body bgcolor="#FFFFFF">

<dl>
    <dd><a href="#NAME">NAME</a> <dl>

        <dd><b>tls</b> - binding to <b>OpenSSL</b> toolkit.</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 tls</b></dd>

|













|
>








1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>

<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Copyright" content="1999 Matt Newman / 2004 Starfish Systems">
<title>TLS (SSL) Tcl Commands</title>
</head>

<body bgcolor="#FFFFFF">

<dl>
    <dd><a href="#NAME">NAME</a>
    <dl>
        <dd><b>tls</b> - binding to <b>OpenSSL</b> toolkit.</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 tls</b></dd>
︙︙
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
281
282
283
284
285
286
287
288
289
290
291
292
293
294

295

296
297
298
299
300
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
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374

    <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>
    <dd>Returns the current certificate status of an SSL channel. The
        result is a list of key-value pairs describing the
        connected peer. If the result is an empty list then the
        SSL handshake has not yet completed.











        If <em>-local</em> is given, then the certificate information








        is the one used locally.</dd>






<blockquote>

    <dl>
        <dt><strong>all</strong> <em>string</em></dt>
        <dd>Dump of all certificate data.</dd>

        <dt><strong>version</strong> <em>value</em></dt>
        <dd>The certification version</dd>


        <dt><strong>signatureAlgorithm</strong> <em>algorithm</em></dt>
        <dd>Cipher algorithm used for certificate signature.</dd>
        <dt><strong>digest</strong> <em>version</em></dt>
        <dd>Certificate signature digest.</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.</dd>
        <dt><strong>bits</strong> <em>n</em></dt>
        <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>
        <dt><strong>sha1_hash</strong> <em>hash</em></dt>
        <dd>The SHA1 hash of the certificate.</dd>
        <dt><strong>sha256_hash</strong> <em>hash</em></dt>
        <dd>The SHA256 hash of the certificate.</dd>
        <dt><strong>subject</strong> <em>dn</em></dt>
        <dd>The distinguished name (DN) of the certificate subject.</dd>
        <dt><strong>issuer</strong> <em>dn</em></dt>
        <dd>The distinguished name (DN) of the certificate issuer.</dd>
        <dt><strong>notBefore</strong> <em>date</em></dt>
        <dd>The begin date for the validity of the certificate.</dd>
        <dt><strong>notAfter</strong> <em>date</em></dt>
        <dd>The expiry date for the certificate.</dd>
        <dt><strong>serialNumber</strong> <em>n</em></dt>
        <dd>The serial number of the certificate.</dd>
        <dt><strong>certificate</strong> <em>cert</em></dt>

        <dd>The PEM encoded certificate.</dd>
        <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>peername</strong> <em>name</em></dt>
        <dd>The peername from the certificate.</dd>
        <dt><strong>sbits</strong> <em>n</em></dt>


        <dd>The number of bits used for the session key.</dd>
        <dt><strong>cipher</strong> <em>cipher</em></dt>
        <dd>The current cipher in use between the client and
            server channels.</dd>
        <dt><strong>verification<em>result</em></dt>
        <dd>Certificate verification result.</dd>
        <dt><strong>alpn</strong> <em>protocol</em></dt>
        <dd>The protocol selected after Application-Layer Protocol
	    Negotiation (ALPN).</dd>
        <dt><strong>protocol</strong> <em>value</em></dt>
        <dd>The protocol version used for the connection:
	  SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3, or unknown</dd>
        <dt><strong>signatureHashAlgorithm</strong> <em>string</em></dt>
        <dd>The signature hash algorithm.</dd>
        <dt><strong>signature_type</strong> <em>type</em></dt>
        <dd>The signature type value.</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>ca_names</strong> <em>list</em></dt>
        <dd>List of the Certificate Authorities used to create the certificate.</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
        connected peer.</dd>

<blockquote>

    <dl>
        <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>state</em></dt>
        <dd>Whether protocol renegotiation is supported or not.</dd>
        <dt><strong>securitylevel</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 configured as a server or client (false).</dd>









        <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>
        <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>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>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>
        <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>string</em></dt>
        <dd>Unique session id for use in resuming the session.</dd>
        <dt><strong>session_ticket</strong> <em>string</em></dt>
        <dd>Unique session ticket for use in resuming the session.</dd>
        <dt><strong>ticket_app_data</strong> <em>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>compression</strong> <em>mode</em></dt>
        <dd>Compression method.</dd>
        <dt><strong>expansion</strong> <em>mode</em></dt>
        <dd>Expansion method.</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








|
|
|
|
>
>
>
>
>
>
>
>
>
>
>
|
>
>
>
>
>
>
>
>
|
|
>
>
>
>
>

>


|
>

|
>
>
|

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<





|
|
|
|
>
|




|
|
|
>
>
|
|
|
|
|
|
|
<
|
<
<
<
|
|
|
|
|
>
|
>
|
|
|








<

>
















>
>
>
>
>
>
>
>
>














>
>
>
>
>



















<
<
<
<





|








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
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300

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
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
395
396
397
398

    <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>
    <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
	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
            server channels.</dd>
        <dt><strong>peername</strong> <em>name</em></dt>
        <dd>The peername from the certificate.</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>sbits</strong> <em>n</em></dt>
        <dd>The number of bits used for the session key.</dd>
        <dt><strong>signatureHashAlgorithm</strong> <em>algorithm</em></dt>
        <dd>The signature hash algorithm.</dd>
        <dt><strong>signature_type</strong> <em>type</em></dt>
        <dd>The signature type value.</dd>
        <dt><strong>verification</strong> <em>result</em></dt>
        <dd>Certificate verification result.</dd>
        <dt><strong>ca_names</strong> <em>list</em></dt>
        <dd>List of the Certificate Authorities used to create the certificate.</dd>
    </dl>
</blockquote>
<blockquote>
	<b>Certificate Status</b>
    <dl>
        <dt><strong>all</strong> <em>string</em></dt>
        <dd>Dump of all certificate info.</dd>

        <dt><strong>version</strong> <em>value</em></dt>
        <dd>The certificate version.</dd>
        <dt><strong>serialNumber</strong> <em>n</em></dt>
        <dd>The serial number of the certificate as hex string.</dd>
        <dt><strong>signature</strong> <em>algorithm</em></dt>
        <dd>Cipher algorithm used for certificate signature.</dd>
















        <dt><strong>issuer</strong> <em>dn</em></dt>
        <dd>The distinguished name (DN) of the certificate issuer.</dd>
        <dt><strong>notBefore</strong> <em>date</em></dt>
        <dd>The begin date for the validity of the certificate.</dd>
        <dt><strong>notAfter</strong> <em>date</em></dt>
        <dd>The expiration date for the certificate.</dd>
        <dt><strong>subject</strong> <em>dn</em></dt>
        <dd>The distinguished name (DN) of the certificate subject.
	    Fields include: Common Name (CN), Organization (O), Locality
	    or City (L), State or Province (S), and Country Name (C).</dd>

        <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>subjectKeyIdentifier</strong> <em>string</em></dt>
        <dd>Hash of the public key inside the certificate.</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>certificate</strong> <em>cert</em></dt>
        <dd>The PEM encoded certificate.</dd>

        <dt><strong>signatureDigest</strong> <em>version</em></dt>
        <dd>Certificate signing digest.</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>
        <dt><strong>bits</strong> <em>n</em></dt>
        <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>

        <dt><strong>sha1_hash</strong> <em>hash</em></dt>
        <dd>The SHA1 hash of the certificate as hex string.</dd>
        <dt><strong>sha256_hash</strong> <em>hash</em></dt>
        <dd>The SHA256 hash of the certificate as 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
        connected peer.</dd>

<blockquote>
	<b>SSL Status</b>
    <dl>
        <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>state</em></dt>
        <dd>Whether protocol renegotiation is supported or not.</dd>
        <dt><strong>securitylevel</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 configured as a server or client (false).</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>
    </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>
        <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>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>
    </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>
        <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>string</em></dt>
        <dd>Unique session id for use in resuming the session.</dd>
        <dt><strong>session_ticket</strong> <em>string</em></dt>
        <dd>Unique session ticket for use in resuming the session.</dd>
        <dt><strong>ticket_app_data</strong> <em>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::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
︙︙
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426

	<dl>

	<dt>
	  <strong>alpn</strong> <em>protocol</em>
	</dt>
	<dd>
	  For servers, this form of callback is invoked when the client ALPN
	  header is received and the first -alpn specified protocol common to
	  the both the client and server is selected. If none, the first
	  client specified protocol is used.
	</dd>

	<br>

<!--	This form of callback is disabled.









|
|








435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450

	<dl>

	<dt>
	  <strong>alpn</strong> <em>protocol</em>
	</dt>
	<dd>
	  For servers, this form of callback is invoked when the client ALPN
	  header is received and the first <b>-alpn</b> specified protocol common
	  to the both the client and server is selected. If none, the first
	  client specified protocol is used.
	</dd>

	<br>

<!--	This form of callback is disabled.
︙︙
Powered by Fossil · RSS