0000: 5b 63 6f 6d 6d 65 6e 74 20 7b 2d 2a 2d 20 74 63 [comment {-*- tc
0010: 6c 20 2d 2a 2d 20 64 6f 63 74 6f 6f 6c 73 20 6d l -*- doctools m
0020: 61 6e 70 61 67 65 7d 5d 0a 5b 63 6f 6d 6d 65 6e anpage}].[commen
0030: 74 20 7b 54 6f 20 63 6f 6e 76 65 72 74 20 74 68 t {To convert th
0040: 69 73 20 74 6f 20 61 6e 6f 74 68 65 72 20 64 6f is to another do
0050: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 6d cumentation form
0060: 61 74 20 75 73 65 20 74 68 65 20 64 74 70 6c 69 at use the dtpli
0070: 74 65 0a 20 20 20 20 20 20 20 20 20 20 73 63 72 te. scr
0080: 69 70 74 20 66 72 6f 6d 20 74 63 6c 6c 69 62 3a ipt from tcllib:
0090: 20 64 74 70 6c 69 74 65 20 2d 6f 20 74 6c 73 2e dtplite -o tls.
00a0: 6e 20 6e 72 6f 66 66 20 74 6c 73 2e 6d 61 6e 0a n nroff tls.man.
00b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
00c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 64 74 dt
00d0: 70 6c 69 74 65 20 2d 6f 20 74 6c 73 2e 68 74 6d plite -o tls.htm
00e0: 6c 20 68 74 6d 6c 20 74 6c 73 2e 6d 61 6e 0a 7d l html tls.man.}
00f0: 5d 0a 5b 6d 61 6e 70 61 67 65 5f 62 65 67 69 6e ].[manpage_begin
0100: 20 74 6c 73 20 6e 20 32 2e 30 62 31 5d 0a 5b 63 tls n 2.0b1].[c
0110: 61 74 65 67 6f 72 79 20 74 6c 73 5d 0a 5b 63 6f ategory tls].[co
0120: 70 79 72 69 67 68 74 20 7b 31 39 39 39 20 4d 61 pyright {1999 Ma
0130: 74 74 20 4e 65 77 6d 61 6e 7d 5d 0a 5b 63 6f 70 tt Newman}].[cop
0140: 79 72 69 67 68 74 20 7b 32 30 30 34 20 53 74 61 yright {2004 Sta
0150: 72 66 69 73 68 20 53 79 73 74 65 6d 73 7d 5d 0a rfish Systems}].
0160: 5b 63 6f 70 79 72 69 67 68 74 20 7b 32 30 32 34 [copyright {2024
0170: 20 42 72 69 61 6e 20 4f 27 48 61 67 61 6e 7d 5d Brian O'Hagan}]
0180: 0a 5b 6b 65 79 77 6f 72 64 73 20 74 6c 73 20 49 .[keywords tls I
0190: 2f 4f 20 22 49 50 20 41 64 64 72 65 73 73 22 20 /O "IP Address"
01a0: 4f 70 65 6e 53 53 4c 20 53 53 4c 20 54 43 50 20 OpenSSL SSL TCP
01b0: 54 4c 53 20 22 61 73 79 6e 63 68 72 6f 6e 6f 75 TLS "asynchronou
01c0: 73 20 49 2f 4f 22 20 62 69 6e 64 20 63 65 72 74 s I/O" bind cert
01d0: 69 66 69 63 61 74 65 20 63 68 61 6e 6e 65 6c 20 ificate channel
01e0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 22 64 6f 6d 61 connection "doma
01f0: 69 6e 20 6e 61 6d 65 22 20 68 6f 73 74 20 22 68 in name" host "h
0200: 74 74 70 73 22 20 22 6e 65 74 77 6f 72 6b 20 61 ttps" "network a
0210: 64 64 72 65 73 73 22 20 6e 65 74 77 6f 72 6b 20 ddress" network
0220: 73 6f 63 6b 65 74 20 54 63 6c 54 4c 53 5d 0a 5b socket TclTLS].[
0230: 6d 6f 64 64 65 73 63 20 7b 54 63 6c 20 54 4c 53 moddesc {Tcl TLS
0240: 20 65 78 74 65 6e 73 69 6f 6e 7d 5d 0a 5b 73 65 extension}].[se
0250: 65 5f 61 6c 73 6f 20 68 74 74 70 20 73 6f 63 6b e_also http sock
0260: 65 74 20 5b 75 72 69 20 68 74 74 70 73 3a 2f 2f et [uri https://
0270: 77 77 77 2e 6f 70 65 6e 73 73 6c 2e 6f 72 67 2f www.openssl.org/
0280: 20 4f 70 65 6e 53 53 4c 5d 5d 0a 5b 74 69 74 6c OpenSSL]].[titl
0290: 65 64 65 73 63 20 7b 62 69 6e 64 69 6e 67 20 74 edesc {binding t
02a0: 6f 20 74 68 65 20 4f 70 65 6e 53 53 4c 20 6c 69 o the OpenSSL li
02b0: 62 72 61 72 79 20 66 6f 72 20 65 6e 63 72 79 70 brary for encryp
02c0: 74 65 64 20 73 6f 63 6b 65 74 20 61 6e 64 20 49 ted socket and I
02d0: 2f 4f 20 63 68 61 6e 6e 65 6c 20 63 6f 6d 6d 75 /O channel commu
02e0: 6e 69 63 61 74 69 6f 6e 73 7d 5d 0a 5b 72 65 71 nications}].[req
02f0: 75 69 72 65 20 54 63 6c 20 38 2e 35 2d 5d 0a 5b uire Tcl 8.5-].[
0300: 72 65 71 75 69 72 65 20 74 6c 73 20 32 2e 30 62 require tls 2.0b
0310: 31 5d 0a 5b 64 65 73 63 72 69 70 74 69 6f 6e 5d 1].[description]
0320: 0a 0a 54 68 69 73 20 65 78 74 65 6e 73 69 6f 6e ..This extension
0330: 20 70 72 6f 76 69 64 65 73 20 54 43 4c 20 73 63 provides TCL sc
0340: 72 69 70 74 20 61 63 63 65 73 73 20 74 6f 20 53 ript access to S
0350: 65 63 75 72 65 20 53 6f 63 6b 65 74 20 4c 61 79 ecure Socket Lay
0360: 65 72 20 28 53 53 4c 29 0a 63 6f 6d 6d 75 6e 69 er (SSL).communi
0370: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 20 74 68 cations using th
0380: 65 20 54 72 61 6e 73 70 6f 72 74 20 4c 61 79 65 e Transport Laye
0390: 72 20 53 65 63 75 72 69 74 79 20 28 54 4c 53 29 r Security (TLS)
03a0: 20 70 72 6f 74 6f 63 6f 6c 2e 20 49 74 20 70 72 protocol. It pr
03b0: 6f 76 69 64 65 73 20 61 0a 67 65 6e 65 72 69 63 ovides a.generic
03c0: 20 62 69 6e 64 69 6e 67 20 74 6f 20 5b 75 72 69 binding to [uri
03d0: 20 22 68 74 74 70 73 3a 2f 2f 77 77 77 2e 6f 70 "https://www.op
03e0: 65 6e 73 73 6c 2e 6f 72 67 2f 22 20 4f 70 65 6e enssl.org/" Open
03f0: 53 53 4c 5d 2c 20 75 74 69 6c 69 7a 69 6e 67 20 SSL], utilizing
0400: 74 68 65 0a 5b 73 79 73 63 6d 64 20 54 63 6c 5f the.[syscmd Tcl_
0410: 53 74 61 63 6b 43 68 61 6e 6e 65 6c 5d 20 41 50 StackChannel] AP
0420: 49 20 69 6e 20 54 43 4c 20 38 2e 34 20 6f 72 20 I in TCL 8.4 or
0430: 6c 61 74 65 72 2e 20 54 68 65 73 65 20 73 6f 63 later. These soc
0440: 6b 65 74 73 20 62 65 68 61 76 65 20 65 78 61 63 kets behave exac
0450: 74 6c 79 0a 74 68 65 20 73 61 6d 65 20 61 73 20 tly.the same as
0460: 63 68 61 6e 6e 65 6c 73 20 63 72 65 61 74 65 64 channels created
0470: 20 75 73 69 6e 67 20 74 68 65 20 62 75 69 6c 74 using the built
0480: 2d 69 6e 20 5b 73 79 73 63 6d 64 20 73 6f 63 6b -in [syscmd sock
0490: 65 74 5d 20 63 6f 6d 6d 61 6e 64 2c 20 62 75 74 et] command, but
04a0: 0a 70 72 6f 76 69 64 65 20 61 64 64 69 74 69 6f .provide additio
04b0: 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 nal options for
04c0: 63 6f 6e 74 72 6f 6c 6c 69 6e 67 20 74 68 65 20 controlling the
04d0: 53 53 4c 2f 54 4c 53 20 73 65 73 73 69 6f 6e 2e SSL/TLS session.
04e0: 0a 0a 5b 73 65 63 74 69 6f 6e 20 43 6f 6d 70 61 ..[section Compa
04f0: 74 69 62 69 6c 69 74 79 5d 0a 54 68 69 73 20 65 tibility].This e
0500: 78 74 65 6e 73 69 6f 6e 20 69 73 20 63 6f 6d 70 xtension is comp
0510: 61 74 69 62 6c 65 20 77 69 74 68 20 4f 70 65 6e atible with Open
0520: 53 53 4c 20 31 2e 31 2e 31 20 6f 72 20 6c 61 74 SSL 1.1.1 or lat
0530: 65 72 2e 20 49 74 20 72 65 71 75 69 72 65 73 20 er. It requires
0540: 54 63 6c 0a 76 65 72 73 69 6f 6e 20 38 2e 35 20 Tcl.version 8.5
0550: 6f 72 20 6c 61 74 65 72 20 61 6e 64 20 77 69 6c or later and wil
0560: 6c 20 77 6f 72 6b 20 77 69 74 68 20 54 63 6c 20 l work with Tcl
0570: 39 2e 30 2e 0a 0a 5b 73 65 63 74 69 6f 6e 20 43 9.0...[section C
0580: 6f 6d 6d 61 6e 64 73 5d 0a 0a 54 68 65 20 66 6f ommands]..The fo
0590: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 llowing are the
05a0: 63 6f 6d 6d 61 6e 64 73 20 70 72 6f 76 69 64 65 commands provide
05b0: 64 20 62 79 20 74 68 65 20 54 63 4c 54 4c 53 20 d by the TcLTLS
05c0: 70 61 63 6b 61 67 65 2e 20 53 65 65 0a 5b 73 65 package. See.[se
05d0: 63 74 72 65 66 20 45 78 61 6d 70 6c 65 73 5d 20 ctref Examples]
05e0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 75 73 61 67 for example usag
05f0: 65 20 61 6e 64 20 74 68 65 20 5b 66 69 6c 65 20 e and the [file
0600: 64 65 6d 6f 73 5d 20 64 69 72 65 63 74 6f 72 79 demos] directory
0610: 20 66 6f 72 0a 6d 6f 72 65 20 65 78 61 6d 70 6c for.more exampl
0620: 65 20 75 73 61 67 65 2e 0a 0a 5b 6c 69 73 74 5f e usage...[list_
0630: 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 6f 6e begin definition
0640: 73 5d 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 74 s]..[call [cmd t
0650: 6c 73 3a 3a 69 6e 69 74 5d 20 5b 6f 70 74 20 5b ls::init] [opt [
0660: 61 72 67 20 2d 6f 70 74 69 6f 6e 5d 5d 20 5b 6f arg -option]] [o
0670: 70 74 20 5b 61 72 67 20 76 61 6c 75 65 5d 5d 20 pt [arg value]]
0680: 5b 6f 70 74 20 5b 61 72 67 20 22 2d 6f 70 74 69 [opt [arg "-opti
0690: 6f 6e 20 76 61 6c 75 65 20 2e 2e 2e 22 5d 5d 5d on value ..."]]]
06a0: 0a 0a 4f 70 74 69 6f 6e 61 6c 20 66 75 6e 63 74 ..Optional funct
06b0: 69 6f 6e 20 74 6f 20 73 65 74 20 74 68 65 20 64 ion to set the d
06c0: 65 66 61 75 6c 74 20 6f 70 74 69 6f 6e 73 20 75 efault options u
06d0: 73 65 64 20 62 79 20 5b 63 6d 64 20 74 6c 73 3a sed by [cmd tls:
06e0: 3a 73 6f 63 6b 65 74 5d 2e 20 49 66 20 79 6f 75 :socket]. If you
06f0: 0a 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a .call [cmd tls::
0700: 69 6d 70 6f 72 74 5d 20 64 69 72 65 63 74 6c 79 import] directly
0710: 2c 20 74 68 65 20 76 61 6c 75 65 73 20 73 65 74 , the values set
0720: 20 62 79 20 74 68 69 73 20 63 6f 6d 6d 61 6e 64 by this command
0730: 20 68 61 76 65 20 6e 6f 20 65 66 66 65 63 74 2e have no effect.
0740: 0a 54 68 69 73 20 63 6f 6d 6d 61 6e 64 20 73 75 .This command su
0750: 70 70 6f 72 74 73 20 61 6c 6c 20 6f 66 20 74 68 pports all of th
0760: 65 20 73 61 6d 65 20 6f 70 74 69 6f 6e 73 20 61 e same options a
0770: 73 20 74 68 65 20 5b 63 6d 64 20 74 6c 73 3a 3a s the [cmd tls::
0780: 73 6f 63 6b 65 74 5d 20 63 6f 6d 6d 61 6e 64 2c socket] command,
0790: 0a 74 68 6f 75 67 68 20 79 6f 75 20 73 68 6f 75 .though you shou
07a0: 6c 64 20 6c 69 6d 69 74 20 79 6f 75 72 20 6f 70 ld limit your op
07b0: 74 69 6f 6e 73 20 74 6f 20 6f 6e 6c 79 20 74 68 tions to only th
07c0: 65 20 54 4c 53 20 72 65 6c 61 74 65 64 20 6f 6e e TLS related on
07d0: 65 73 2e 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 es...[call [cmd
07e0: 74 6c 73 3a 3a 73 6f 63 6b 65 74 5d 20 5b 6f 70 tls::socket] [op
07f0: 74 20 5b 61 72 67 20 2d 6f 70 74 69 6f 6e 5d 5d t [arg -option]]
0800: 20 5b 6f 70 74 20 5b 61 72 67 20 76 61 6c 75 65 [opt [arg value
0810: 5d 5d 20 5b 6f 70 74 20 5b 61 72 67 20 22 2d 6f ]] [opt [arg "-o
0820: 70 74 69 6f 6e 20 76 61 6c 75 65 20 2e 2e 2e 22 ption value ..."
0830: 5d 5d 20 5b 61 72 67 20 68 6f 73 74 5d 20 5b 61 ]] [arg host] [a
0840: 72 67 20 70 6f 72 74 5d 5d 0a 0a 54 68 69 73 20 rg port]]..This
0850: 69 73 20 61 20 68 65 6c 70 65 72 20 66 75 6e 63 is a helper func
0860: 74 69 6f 6e 20 74 68 61 74 20 75 74 69 6c 69 7a tion that utiliz
0870: 65 73 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e es the underlyin
0880: 67 20 63 6f 6d 6d 61 6e 64 73 20 5b 73 79 73 63 g commands [sysc
0890: 6d 64 20 73 6f 63 6b 65 74 5d 0a 61 6e 64 20 5b md socket].and [
08a0: 63 6d 64 20 74 6c 73 3a 3a 69 6d 70 6f 72 74 5d cmd tls::import]
08b0: 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 63 to create the c
08c0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 49 74 20 62 65 onnection. It be
08d0: 68 61 76 65 73 20 74 68 65 20 73 61 6d 65 20 61 haves the same a
08e0: 73 20 74 68 65 0a 6e 61 74 69 76 65 20 54 43 4c s the.native TCL
08f0: 20 5b 73 79 73 63 6d 64 20 73 6f 63 6b 65 74 5d [syscmd socket]
0900: 20 63 6f 6d 6d 61 6e 64 2c 20 62 75 74 20 61 6c command, but al
0910: 73 6f 20 73 75 70 70 6f 72 74 73 20 74 68 65 20 so supports the
0920: 5b 63 6d 64 20 74 6c 73 3a 3a 69 6d 70 6f 72 74 [cmd tls::import
0930: 5d 0a 63 6f 6d 6d 61 6e 64 20 6f 70 74 69 6f 6e ].command option
0940: 73 20 77 69 74 68 20 6f 6e 65 20 61 64 64 69 74 s with one addit
0950: 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e 2e 20 49 74 ional option. It
0960: 20 72 65 74 75 72 6e 73 20 74 68 65 20 63 68 61 returns the cha
0970: 6e 6e 65 6c 20 68 61 6e 64 6c 65 20 69 64 0a 66 nnel handle id.f
0980: 6f 72 20 74 68 65 20 6e 65 77 20 73 6f 63 6b 65 or the new socke
0990: 74 2e 20 41 64 64 69 74 69 6f 6e 61 6c 20 6f 70 t. Additional op
09a0: 74 69 6f 6e 73 20 61 72 65 3a 0a 0a 5b 6c 69 73 tions are:..[lis
09b0: 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f 6e 73 5d t_begin options]
09c0: 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 61 75 74 6f ..[opt_def -auto
09d0: 73 65 72 76 65 72 6e 61 6d 65 20 5b 61 72 67 20 servername [arg
09e0: 62 6f 6f 6c 5d 5d 0a 49 66 20 5b 63 6f 6e 73 74 bool]].If [const
09f0: 20 74 72 75 65 5d 2c 20 61 75 74 6f 6d 61 74 69 true], automati
0a00: 63 61 6c 6c 79 20 73 65 74 20 74 68 65 20 5b 6f cally set the [o
0a10: 70 74 69 6f 6e 20 2d 73 65 72 76 65 72 6e 61 6d ption -servernam
0a20: 65 5d 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 e] argument to t
0a30: 68 65 0a 5b 65 6d 70 68 20 68 6f 73 74 5d 20 61 he.[emph host] a
0a40: 72 67 75 6d 65 6e 74 2e 20 50 72 69 6f 72 20 74 rgument. Prior t
0a50: 6f 20 54 63 6c 54 4c 53 20 32 2e 30 2c 20 74 68 o TclTLS 2.0, th
0a60: 65 20 64 65 66 61 75 6c 74 20 69 73 20 5b 63 6f e default is [co
0a70: 6e 73 74 20 66 61 6c 73 65 5d 2e 0a 53 74 61 72 nst false]..Star
0a80: 74 69 6e 67 20 69 6e 20 54 63 6c 54 4c 53 20 32 ting in TclTLS 2
0a90: 2e 30 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 .0, the default
0aa0: 69 73 20 5b 63 6f 6e 73 74 20 74 72 75 65 5d 20 is [const true]
0ab0: 75 6e 6c 65 73 73 20 5b 6f 70 74 69 6f 6e 20 2d unless [option -
0ac0: 73 65 72 76 65 72 6e 61 6d 65 5d 0a 69 73 20 61 servername].is a
0ad0: 6c 73 6f 20 73 70 65 63 69 66 69 65 64 2e 0a 0a lso specified...
0ae0: 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 63 61 6c [list_end]..[cal
0af0: 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a 73 6f 63 6b l [cmd tls::sock
0b00: 65 74 5d 20 5b 6f 70 74 69 6f 6e 20 2d 73 65 72 et] [option -ser
0b10: 76 65 72 5d 20 5b 61 72 67 20 63 6f 6d 6d 61 6e ver] [arg comman
0b20: 64 5d 20 5b 6f 70 74 20 5b 61 72 67 20 2d 6f 70 d] [opt [arg -op
0b30: 74 69 6f 6e 5d 5d 20 5b 6f 70 74 20 5b 61 72 67 tion]] [opt [arg
0b40: 20 76 61 6c 75 65 5d 5d 20 5b 6f 70 74 20 5b 61 value]] [opt [a
0b50: 72 67 20 22 2d 6f 70 74 69 6f 6e 20 76 61 6c 75 rg "-option valu
0b60: 65 20 2e 2e 2e 22 5d 5d 20 5b 61 72 67 20 70 6f e ..."]] [arg po
0b70: 72 74 5d 5d 0a 0a 53 61 6d 65 20 61 73 20 70 72 rt]]..Same as pr
0b80: 65 76 69 6f 75 73 20 63 6f 6d 6d 61 6e 64 2c 20 evious command,
0b90: 62 75 74 20 69 6e 73 74 65 61 64 20 63 72 65 61 but instead crea
0ba0: 74 65 73 20 61 20 73 65 72 76 65 72 20 73 6f 63 tes a server soc
0bb0: 6b 65 74 20 66 6f 72 20 63 6c 69 65 6e 74 73 20 ket for clients
0bc0: 74 6f 0a 63 6f 6e 6e 65 63 74 20 74 6f 20 6a 75 to.connect to ju
0bd0: 73 74 20 6c 69 6b 65 20 74 68 65 20 54 63 6c 20 st like the Tcl
0be0: 5b 73 79 73 63 6d 64 20 22 73 6f 63 6b 65 74 20 [syscmd "socket
0bf0: 2d 73 65 72 76 65 72 22 5d 20 63 6f 6d 6d 61 6e -server"] comman
0c00: 64 2e 20 49 74 20 72 65 74 75 72 6e 73 20 74 68 d. It returns th
0c10: 65 0a 63 68 61 6e 6e 65 6c 20 68 61 6e 64 6c 65 e.channel handle
0c20: 20 69 64 20 66 6f 72 20 74 68 65 20 6e 65 77 20 id for the new
0c30: 73 6f 63 6b 65 74 2e 0a 0a 5b 63 61 6c 6c 20 5b socket...[call [
0c40: 63 6d 64 20 74 6c 73 3a 3a 69 6d 70 6f 72 74 5d cmd tls::import]
0c50: 20 5b 61 72 67 20 63 68 61 6e 6e 65 6c 5d 20 5b [arg channel] [
0c60: 6f 70 74 20 5b 61 72 67 20 2d 6f 70 74 69 6f 6e opt [arg -option
0c70: 5d 5d 20 5b 6f 70 74 20 5b 61 72 67 20 76 61 6c ]] [opt [arg val
0c80: 75 65 5d 5d 20 5b 6f 70 74 20 5b 61 72 67 20 22 ue]] [opt [arg "
0c90: 2d 6f 70 74 69 6f 6e 20 76 61 6c 75 65 20 2e 2e -option value ..
0ca0: 2e 22 5d 5d 5d 0a 0a 53 74 61 72 74 20 54 4c 53 ."]]]..Start TLS
0cb0: 20 65 6e 63 72 79 70 74 69 6f 6e 20 6f 6e 20 54 encryption on T
0cc0: 43 4c 20 63 68 61 6e 6e 65 6c 20 5b 61 72 67 20 CL channel [arg
0cd0: 63 68 61 6e 6e 65 6c 5d 20 76 69 61 20 61 20 73 channel] via a s
0ce0: 74 61 63 6b 65 64 20 63 68 61 6e 6e 65 6c 2e 20 tacked channel.
0cf0: 49 74 0a 6e 65 65 64 20 6e 6f 74 20 62 65 20 61 It.need not be a
0d00: 20 73 6f 63 6b 65 74 2c 20 62 75 74 20 6d 75 73 socket, but mus
0d10: 74 20 70 72 6f 76 69 64 65 20 62 69 2d 64 69 72 t provide bi-dir
0d20: 65 63 74 69 6f 6e 61 6c 20 66 6c 6f 77 2e 20 41 ectional flow. A
0d30: 6c 73 6f 20 73 65 74 73 20 73 65 73 73 69 6f 6e lso sets session
0d40: 0a 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 .parameters for
0d50: 53 53 4c 20 68 61 6e 64 73 68 61 6b 65 2e 20 56 SSL handshake. V
0d60: 61 6c 69 64 20 6f 70 74 69 6f 6e 73 20 61 72 65 alid options are
0d70: 3a 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e 20 6f :..[list_begin o
0d80: 70 74 69 6f 6e 73 5d 0a 0a 5b 6f 70 74 5f 64 65 ptions]..[opt_de
0d90: 66 20 2d 61 6c 70 6e 20 5b 61 72 67 20 6c 69 73 f -alpn [arg lis
0da0: 74 5d 5d 0a 4c 69 73 74 20 6f 66 20 70 72 6f 74 t]].List of prot
0db0: 6f 63 6f 6c 73 20 74 6f 20 6f 66 66 65 72 20 64 ocols to offer d
0dc0: 75 72 69 6e 67 20 41 70 70 6c 69 63 61 74 69 6f uring Applicatio
0dd0: 6e 2d 4c 61 79 65 72 20 50 72 6f 74 6f 63 6f 6c n-Layer Protocol
0de0: 20 4e 65 67 6f 74 69 61 74 69 6f 6e 0a 28 41 4c Negotiation.(AL
0df0: 50 4e 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 PN). For example
0e00: 3a 20 5b 63 6f 6e 73 74 20 68 32 5d 20 61 6e 64 : [const h2] and
0e10: 20 5b 63 6f 6e 73 74 20 68 74 74 70 2f 31 2e 31 [const http/1.1
0e20: 5d 2c 20 62 75 74 20 6e 6f 74 20 5b 63 6f 6e 73 ], but not [cons
0e30: 74 20 68 33 5d 20 6f 72 0a 5b 63 6f 6e 73 74 20 t h3] or.[const
0e40: 71 75 69 63 5d 2e 20 54 68 69 73 20 6f 70 74 69 quic]. This opti
0e50: 6f 6e 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 on is new for Tc
0e60: 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 6f 70 74 5f lTLS 1.8...[opt_
0e70: 64 65 66 20 2d 63 61 64 69 72 20 5b 61 72 67 20 def -cadir [arg
0e80: 64 69 72 65 63 74 6f 72 79 5d 5d 0a 53 70 65 63 directory]].Spec
0e90: 69 66 69 65 73 20 74 68 65 20 64 69 72 65 63 74 ifies the direct
0ea0: 6f 72 79 20 77 68 65 72 65 20 74 68 65 20 43 65 ory where the Ce
0eb0: 72 74 69 66 69 63 61 74 65 20 41 75 74 68 6f 72 rtificate Author
0ec0: 69 74 79 20 28 43 41 29 20 63 65 72 74 69 66 69 ity (CA) certifi
0ed0: 63 61 74 65 73 20 61 72 65 0a 73 74 6f 72 65 64 cates are.stored
0ee0: 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 . The default is
0ef0: 20 70 6c 61 74 66 6f 72 6d 20 73 70 65 63 69 66 platform specif
0f00: 69 63 20 61 6e 64 20 63 61 6e 20 62 65 20 73 65 ic and can be se
0f10: 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d t at compile tim
0f20: 65 2e 20 54 68 65 0a 64 65 66 61 75 6c 74 20 6c e. The.default l
0f30: 6f 63 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 6f ocation can be o
0f40: 76 65 72 72 69 64 64 65 6e 20 62 79 20 74 68 65 verridden by the
0f50: 20 5b 76 61 72 20 53 53 4c 5f 43 45 52 54 5f 44 [var SSL_CERT_D
0f60: 49 52 5d 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 0a IR] environment.
0f70: 76 61 72 69 61 62 6c 65 2e 20 53 65 65 20 5b 73 variable. See [s
0f80: 65 63 74 72 65 66 20 22 43 65 72 74 69 66 69 63 ectref "Certific
0f90: 61 74 65 20 56 61 6c 69 64 61 74 69 6f 6e 22 5d ate Validation"]
0fa0: 20 66 6f 72 20 6d 6f 72 65 20 64 65 74 61 69 6c for more detail
0fb0: 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 61 s...[opt_def -ca
0fc0: 66 69 6c 65 20 5b 61 72 67 20 66 69 6c 65 6e 61 file [arg filena
0fd0: 6d 65 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 me]].Specifies t
0fe0: 68 65 20 66 69 6c 65 20 77 69 74 68 20 74 68 65 he file with the
0ff0: 20 43 65 72 74 69 66 69 63 61 74 65 20 41 75 74 Certificate Aut
1000: 68 6f 72 69 74 79 20 28 43 41 29 20 63 65 72 74 hority (CA) cert
1010: 69 66 69 63 61 74 65 73 20 74 6f 20 75 73 65 20 ificates to use
1020: 69 6e 0a 5b 63 6f 6e 73 74 20 50 45 4d 5d 20 66 in.[const PEM] f
1030: 69 6c 65 20 66 6f 72 6d 61 74 2e 20 54 68 65 20 ile format. The
1040: 64 65 66 61 75 6c 74 20 69 73 20 5b 66 69 6c 65 default is [file
1050: 20 63 65 72 74 2e 70 65 6d 5d 2c 20 69 6e 20 74 cert.pem], in t
1060: 68 65 20 4f 70 65 6e 53 53 4c 0a 64 69 72 65 63 he OpenSSL.direc
1070: 74 6f 72 79 2e 20 54 68 65 20 64 65 66 61 75 6c tory. The defaul
1080: 74 20 66 69 6c 65 20 63 61 6e 20 62 65 20 6f 76 t file can be ov
1090: 65 72 72 69 64 64 65 6e 20 62 79 20 74 68 65 20 erridden by the
10a0: 5b 76 61 72 20 53 53 4c 5f 43 45 52 54 5f 46 49 [var SSL_CERT_FI
10b0: 4c 45 5d 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 0a LE] environment.
10c0: 76 61 72 69 61 62 6c 65 2e 20 53 65 65 20 5b 73 variable. See [s
10d0: 65 63 74 72 65 66 20 22 43 65 72 74 69 66 69 63 ectref "Certific
10e0: 61 74 65 20 56 61 6c 69 64 61 74 69 6f 6e 22 5d ate Validation"]
10f0: 20 66 6f 72 20 6d 6f 72 65 20 64 65 74 61 69 6c for more detail
1100: 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 61 s...[opt_def -ca
1110: 73 74 6f 72 65 20 5b 61 72 67 20 55 52 49 5d 5d store [arg URI]]
1120: 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 20 55 .Specifies the U
1130: 6e 69 66 6f 72 6d 20 52 65 73 6f 75 72 63 65 20 niform Resource
1140: 49 64 65 6e 74 69 66 69 65 72 20 28 55 52 49 29 Identifier (URI)
1150: 20 66 6f 72 20 74 68 65 20 43 65 72 74 69 66 69 for the Certifi
1160: 63 61 74 65 20 41 75 74 68 6f 72 69 74 79 0a 28 cate Authority.(
1170: 43 41 29 20 73 74 6f 72 65 2c 20 77 68 69 63 68 CA) store, which
1180: 20 6d 61 79 20 62 65 20 61 20 73 69 6e 67 6c 65 may be a single
1190: 20 63 6f 6e 74 61 69 6e 65 72 20 6f 72 20 61 20 container or a
11a0: 63 61 74 61 6c 6f 67 20 6f 66 20 63 6f 6e 74 61 catalog of conta
11b0: 69 6e 65 72 73 2e 0a 53 74 61 72 74 69 6e 67 20 iners..Starting
11c0: 77 69 74 68 20 4f 70 65 6e 53 53 4c 20 33 2e 32 with OpenSSL 3.2
11d0: 20 6f 6e 20 4d 53 20 57 69 6e 64 6f 77 73 2c 20 on MS Windows,
11e0: 73 65 74 20 74 6f 20 22 5b 63 6f 6e 73 74 20 22 set to "[const "
11f0: 6f 72 67 2e 6f 70 65 6e 73 73 6c 2e 77 69 6e 73 org.openssl.wins
1200: 74 6f 72 65 3a 2f 2f 22 5d 22 0a 74 6f 20 75 73 tore://"]".to us
1210: 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 4d e the built-in M
1220: 53 20 57 69 6e 64 6f 77 73 20 43 65 72 74 69 66 S Windows Certif
1230: 69 63 61 74 65 20 53 74 6f 72 65 2e 0a 53 65 65 icate Store..See
1240: 20 5b 73 65 63 74 72 65 66 20 22 43 65 72 74 69 [sectref "Certi
1250: 66 69 63 61 74 65 20 56 61 6c 69 64 61 74 69 6f ficate Validatio
1260: 6e 22 5d 20 66 6f 72 20 6d 6f 72 65 20 64 65 74 n"] for more det
1270: 61 69 6c 73 2e 0a 54 68 69 73 20 6f 70 74 69 6f ails..This optio
1280: 6e 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c n is new for Tcl
1290: 54 4c 53 20 31 2e 38 2e 0a 0a 5b 6f 70 74 5f 64 TLS 1.8...[opt_d
12a0: 65 66 20 2d 63 65 72 74 66 69 6c 65 20 5b 61 72 ef -certfile [ar
12b0: 67 20 66 69 6c 65 6e 61 6d 65 5d 5d 0a 53 70 65 g filename]].Spe
12c0: 63 69 66 69 65 73 20 74 68 65 20 6e 61 6d 65 20 cifies the name
12d0: 6f 66 20 74 68 65 20 66 69 6c 65 20 77 69 74 68 of the file with
12e0: 20 74 68 65 20 63 65 72 74 69 66 69 63 61 74 65 the certificate
12f0: 20 74 6f 20 75 73 65 20 69 6e 20 50 45 4d 20 66 to use in PEM f
1300: 6f 72 6d 61 74 0a 61 73 20 74 68 65 20 6c 6f 63 ormat.as the loc
1310: 61 6c 20 28 63 6c 69 65 6e 74 20 6f 72 20 73 65 al (client or se
1320: 72 76 65 72 29 20 63 65 72 74 69 66 69 63 61 74 rver) certificat
1330: 65 2e 20 49 74 20 61 6c 73 6f 20 63 6f 6e 74 61 e. It also conta
1340: 69 6e 73 20 74 68 65 20 70 75 62 6c 69 63 20 6b ins the public k
1350: 65 79 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 ey...[opt_def -c
1360: 65 72 74 20 5b 61 72 67 20 73 74 72 69 6e 67 5d ert [arg string]
1370: 5d 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 20 ].Specifies the
1380: 63 65 72 74 69 66 69 63 61 74 65 20 74 6f 20 75 certificate to u
1390: 73 65 20 61 73 20 61 20 44 45 52 20 65 6e 63 6f se as a DER enco
13a0: 64 65 64 20 73 74 72 69 6e 67 20 28 58 2e 35 30 ded string (X.50
13b0: 39 20 44 45 52 29 2e 0a 0a 5b 6f 70 74 5f 64 65 9 DER)...[opt_de
13c0: 66 20 2d 63 69 70 68 65 72 20 5b 61 72 67 20 73 f -cipher [arg s
13d0: 74 72 69 6e 67 5d 5d 0a 53 70 65 63 69 66 69 65 tring]].Specifie
13e0: 73 20 74 68 65 20 6c 69 73 74 20 6f 66 20 63 69 s the list of ci
13f0: 70 68 65 72 73 20 74 6f 20 75 73 65 20 66 6f 72 phers to use for
1400: 20 54 4c 53 20 31 2e 32 20 61 6e 64 20 65 61 72 TLS 1.2 and ear
1410: 6c 69 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 lier connections
1420: 2e 0a 53 74 72 69 6e 67 20 69 73 20 61 20 63 6f ..String is a co
1430: 6c 6f 6e 20 22 5b 63 6f 6e 73 74 20 3a 5d 22 20 lon "[const :]"
1440: 73 65 70 61 72 61 74 65 64 20 6c 69 73 74 20 6f separated list o
1450: 66 20 63 69 70 68 65 72 73 2e 0a 43 69 70 68 65 f ciphers..Ciphe
1460: 72 73 20 63 61 6e 20 62 65 20 63 6f 6d 62 69 6e rs can be combin
1470: 65 64 20 75 73 69 6e 67 20 74 68 65 20 22 5b 63 ed using the "[c
1480: 6f 6e 73 74 20 2b 5d 22 20 63 68 61 72 61 63 74 onst +]" charact
1490: 65 72 2e 0a 50 72 65 66 69 78 65 73 20 63 61 6e er..Prefixes can
14a0: 20 62 65 20 75 73 65 64 20 74 6f 20 70 65 72 6d be used to perm
14b0: 61 6e 65 6e 74 6c 79 20 72 65 6d 6f 76 65 20 22 anently remove "
14c0: 5b 63 6f 6e 73 74 20 21 5d 22 2c 20 64 65 6c 65 [const !]", dele
14d0: 74 65 20 22 5b 63 6f 6e 73 74 20 2d 5d 22 2c 20 te "[const -]",
14e0: 6f 72 0a 6d 6f 76 65 20 74 6f 20 74 68 65 20 65 or.move to the e
14f0: 6e 64 20 22 5b 63 6f 6e 73 74 20 2b 5d 22 20 61 nd "[const +]" a
1500: 20 73 70 65 63 69 66 69 65 64 20 63 69 70 68 65 specified ciphe
1510: 72 2e 0a 4b 65 79 77 6f 72 64 73 20 5b 63 6f 6e r..Keywords [con
1520: 73 74 20 40 53 54 52 45 4e 47 54 48 5d 20 28 73 st @STRENGTH] (s
1530: 6f 72 74 20 62 79 20 61 6c 67 6f 72 69 74 68 6d ort by algorithm
1540: 20 6b 65 79 20 6c 65 6e 67 74 68 29 2c 0a 5b 63 key length),.[c
1550: 6f 6e 73 74 20 40 53 45 43 4c 45 56 45 4c 3d 5d onst @SECLEVEL=]
1560: 5b 65 6d 70 68 20 6e 5d 20 28 73 65 74 20 73 65 [emph n] (set se
1570: 63 75 72 69 74 79 20 6c 65 76 65 6c 20 74 6f 20 curity level to
1580: 6e 29 2c 20 61 6e 64 0a 5b 63 6f 6e 73 74 20 44 n), and.[const D
1590: 45 46 41 55 4c 54 5d 20 28 75 73 65 20 64 65 66 EFAULT] (use def
15a0: 61 75 6c 74 20 63 69 70 68 65 72 20 6c 69 73 74 ault cipher list
15b0: 2c 20 61 74 20 73 74 61 72 74 20 6f 6e 6c 79 29 , at start only)
15c0: 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 73 70 65 can also be spe
15d0: 63 69 66 69 65 64 2e 0a 53 65 65 20 74 68 65 20 cified..See the
15e0: 5b 75 72 69 20 22 68 74 74 70 73 3a 2f 2f 64 6f [uri "https://do
15f0: 63 73 2e 6f 70 65 6e 73 73 6c 2e 6f 72 67 2f 6d cs.openssl.org/m
1600: 61 73 74 65 72 2f 6d 61 6e 31 2f 6f 70 65 6e 73 aster/man1/opens
1610: 73 6c 2d 63 69 70 68 65 72 73 2f 23 6f 70 74 69 sl-ciphers/#opti
1620: 6f 6e 73 22 20 4f 70 65 6e 53 53 4c 5d 0a 64 6f ons" OpenSSL].do
1630: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
1640: 74 68 65 20 66 75 6c 6c 20 6c 69 73 74 20 6f 66 the full list of
1650: 20 76 61 6c 69 64 20 76 61 6c 75 65 73 2e 0a 0a valid values...
1660: 5b 6f 70 74 5f 64 65 66 20 2d 63 69 70 68 65 72 [opt_def -cipher
1670: 73 75 69 74 65 73 20 5b 61 72 67 20 73 74 72 69 suites [arg stri
1680: 6e 67 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 ng]].Specifies t
1690: 68 65 20 6c 69 73 74 20 6f 66 20 63 69 70 68 65 he list of ciphe
16a0: 72 20 73 75 69 74 65 73 20 74 6f 20 75 73 65 20 r suites to use
16b0: 66 6f 72 20 54 4c 53 20 31 2e 33 20 61 73 20 61 for TLS 1.3 as a
16c0: 20 63 6f 6c 6f 6e 0a 22 5b 63 6f 6e 73 74 20 3a colon."[const :
16d0: 5d 22 20 73 65 70 61 72 61 74 65 64 20 6c 69 73 ]" separated lis
16e0: 74 20 6f 66 20 63 69 70 68 65 72 20 73 75 69 74 t of cipher suit
16f0: 65 20 6e 61 6d 65 73 2e 20 53 65 65 20 74 68 65 e names. See the
1700: 0a 5b 75 72 69 20 22 68 74 74 70 73 3a 2f 2f 64 .[uri "https://d
1710: 6f 63 73 2e 6f 70 65 6e 73 73 6c 2e 6f 72 67 2f ocs.openssl.org/
1720: 6d 61 73 74 65 72 2f 6d 61 6e 31 2f 6f 70 65 6e master/man1/open
1730: 73 73 6c 2d 63 69 70 68 65 72 73 2f 23 6f 70 74 ssl-ciphers/#opt
1740: 69 6f 6e 73 22 20 4f 70 65 6e 53 53 4c 5d 0a 64 ions" OpenSSL].d
1750: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
1760: 20 74 68 65 20 66 75 6c 6c 20 6c 69 73 74 20 6f the full list o
1770: 66 20 76 61 6c 69 64 20 76 61 6c 75 65 73 2e 0a f valid values..
1780: 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e This option is n
1790: 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e ew for TclTLS 1.
17a0: 38 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 6f 8...[opt_def -co
17b0: 6d 6d 61 6e 64 20 5b 61 72 67 20 63 61 6c 6c 62 mmand [arg callb
17c0: 61 63 6b 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 ack]].Specifies
17d0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6d the callback com
17e0: 6d 61 6e 64 20 74 6f 20 62 65 20 69 6e 76 6f 6b mand to be invok
17f0: 65 64 20 61 74 20 73 65 76 65 72 61 6c 20 70 6f ed at several po
1800: 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 0a ints during the.
1810: 68 61 6e 64 73 68 61 6b 65 20 74 6f 20 70 61 73 handshake to pas
1820: 73 20 65 72 72 6f 72 73 2c 20 74 72 61 63 69 6e s errors, tracin
1830: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 g information, a
1840: 6e 64 20 70 72 6f 74 6f 63 6f 6c 20 6d 65 73 73 nd protocol mess
1850: 61 67 65 73 2e 0a 53 65 65 20 5b 73 65 63 74 72 ages..See [sectr
1860: 65 66 20 22 43 61 6c 6c 62 61 63 6b 20 4f 70 74 ef "Callback Opt
1870: 69 6f 6e 73 22 5d 20 66 6f 72 20 6d 6f 72 65 20 ions"] for more
1880: 69 6e 66 6f 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 info...[opt_def
1890: 2d 64 68 70 61 72 61 6d 73 20 5b 61 72 67 20 66 -dhparams [arg f
18a0: 69 6c 65 6e 61 6d 65 5d 5d 0a 53 70 65 63 69 66 ilename]].Specif
18b0: 69 65 73 20 74 68 65 20 44 69 66 66 69 65 2d 48 ies the Diffie-H
18c0: 65 6c 6c 6d 61 6e 20 28 44 48 29 20 70 61 72 61 ellman (DH) para
18d0: 6d 65 74 65 72 73 20 66 69 6c 65 2e 0a 0a 5b 6f meters file...[o
18e0: 70 74 5f 64 65 66 20 2d 6b 65 79 66 69 6c 65 20 pt_def -keyfile
18f0: 5b 61 72 67 20 66 69 6c 65 6e 61 6d 65 5d 5d 0a [arg filename]].
1900: 53 70 65 63 69 66 69 65 73 20 74 68 65 20 70 72 Specifies the pr
1910: 69 76 61 74 65 20 6b 65 79 20 66 69 6c 65 2e 20 ivate key file.
1920: 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 74 The default is t
1930: 6f 20 75 73 65 20 74 68 65 20 66 69 6c 65 0a 73 o use the file.s
1940: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
1950: 5b 6f 70 74 69 6f 6e 20 2d 63 65 72 74 66 69 6c [option -certfil
1960: 65 5d 20 6f 70 74 69 6f 6e 2e 0a 0a 5b 6f 70 74 e] option...[opt
1970: 5f 64 65 66 20 2d 6b 65 79 20 5b 61 72 67 20 73 _def -key [arg s
1980: 74 72 69 6e 67 5d 5d 0a 53 70 65 63 69 66 69 65 tring]].Specifie
1990: 73 20 74 68 65 20 70 72 69 76 61 74 65 20 6b 65 s the private ke
19a0: 79 20 74 6f 20 75 73 65 20 61 73 20 61 20 44 45 y to use as a DE
19b0: 52 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 R encoded string
19c0: 20 28 50 4b 43 53 23 31 20 44 45 52 29 2e 0a 0a (PKCS#1 DER)...
19d0: 5b 6f 70 74 5f 64 65 66 20 2d 6d 6f 64 65 6c 20 [opt_def -model
19e0: 5b 61 72 67 20 63 68 61 6e 6e 65 6c 5d 5d 0a 46 [arg channel]].F
19f0: 6f 72 63 65 20 74 68 69 73 20 63 68 61 6e 6e 65 orce this channe
1a00: 6c 20 74 6f 20 73 68 61 72 65 20 74 68 65 20 73 l to share the s
1a10: 61 6d 65 20 5b 74 65 72 6d 20 53 53 4c 5f 43 54 ame [term SSL_CT
1a20: 58 5d 20 73 74 72 75 63 74 75 72 65 20 61 73 20 X] structure as
1a30: 74 68 65 0a 73 70 65 63 69 66 69 65 64 20 5b 61 the.specified [a
1a40: 72 67 20 63 68 61 6e 6e 65 6c 5d 2c 20 61 6e 64 rg channel], and
1a50: 20 74 68 65 72 65 66 6f 72 65 20 73 68 61 72 65 therefore share
1a60: 20 63 6f 6e 66 69 67 2c 20 63 61 6c 6c 62 61 63 config, callbac
1a70: 6b 73 2c 20 65 74 63 2e 0a 0a 5b 6f 70 74 5f 64 ks, etc...[opt_d
1a80: 65 66 20 2d 70 61 73 73 77 6f 72 64 20 5b 61 72 ef -password [ar
1a90: 67 20 63 61 6c 6c 62 61 63 6b 5d 5d 0a 53 70 65 g callback]].Spe
1aa0: 63 69 66 69 65 73 20 74 68 65 20 63 61 6c 6c 62 cifies the callb
1ab0: 61 63 6b 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 69 ack command to i
1ac0: 6e 76 6f 6b 65 20 77 68 65 6e 20 4f 70 65 6e 53 nvoke when OpenS
1ad0: 53 4c 20 6e 65 65 64 73 20 74 6f 20 6f 62 74 61 SL needs to obta
1ae0: 69 6e 20 61 0a 70 61 73 73 77 6f 72 64 2e 20 54 in a.password. T
1af0: 68 69 73 20 69 73 20 74 79 70 69 63 61 6c 6c 79 his is typically
1b00: 20 75 73 65 64 20 74 6f 20 75 6e 6c 6f 63 6b 20 used to unlock
1b10: 74 68 65 20 70 72 69 76 61 74 65 20 6b 65 79 20 the private key
1b20: 6f 66 20 61 20 63 65 72 74 69 66 69 63 61 74 65 of a certificate
1b30: 2e 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 73 ..The callback s
1b40: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 61 20 70 hould return a p
1b50: 61 73 73 77 6f 72 64 20 73 74 72 69 6e 67 2e 20 assword string.
1b60: 54 68 69 73 20 6f 70 74 69 6f 6e 20 68 61 73 20 This option has
1b70: 63 68 61 6e 67 65 64 20 66 6f 72 0a 54 63 6c 54 changed for.TclT
1b80: 4c 53 20 31 2e 38 2e 20 53 65 65 20 5b 73 65 63 LS 1.8. See [sec
1b90: 74 72 65 66 20 22 43 61 6c 6c 62 61 63 6b 20 4f tref "Callback O
1ba0: 70 74 69 6f 6e 73 22 5d 20 66 6f 72 20 6d 6f 72 ptions"] for mor
1bb0: 65 20 69 6e 66 6f 2e 0a 0a 5b 6f 70 74 5f 64 65 e info...[opt_de
1bc0: 66 20 2d 70 6f 73 74 5f 68 61 6e 64 73 68 61 6b f -post_handshak
1bd0: 65 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 41 6c e [arg bool]].Al
1be0: 6c 6f 77 20 70 6f 73 74 2d 68 61 6e 64 73 68 61 low post-handsha
1bf0: 6b 65 20 73 65 73 73 69 6f 6e 20 74 69 63 6b 65 ke session ticke
1c00: 74 20 75 70 64 61 74 65 73 2e 20 54 68 69 73 20 t updates. This
1c10: 6f 70 74 69 6f 6e 20 69 73 20 6e 65 77 20 66 6f option is new fo
1c20: 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b r TclTLS 1.8...[
1c30: 6f 70 74 5f 64 65 66 20 2d 72 65 71 75 65 73 74 opt_def -request
1c40: 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 52 65 71 [arg bool]].Req
1c50: 75 65 73 74 20 61 20 63 65 72 74 69 66 69 63 61 uest a certifica
1c60: 74 65 20 66 72 6f 6d 20 74 68 65 20 70 65 65 72 te from the peer
1c70: 20 64 75 72 69 6e 67 20 74 68 65 20 53 53 4c 20 during the SSL
1c80: 68 61 6e 64 73 68 61 6b 65 2e 20 54 68 69 73 20 handshake. This
1c90: 69 73 20 6e 65 65 64 65 64 0a 74 6f 20 64 6f 20 is needed.to do
1ca0: 43 65 72 74 69 66 69 63 61 74 65 20 56 61 6c 69 Certificate Vali
1cb0: 64 61 74 69 6f 6e 2e 20 53 74 61 72 74 69 6e 67 dation. Starting
1cc0: 20 69 6e 20 54 63 6c 54 4c 53 20 31 2e 38 2c 20 in TclTLS 1.8,
1cd0: 74 68 65 20 64 65 66 61 75 6c 74 20 69 73 0a 5b the default is.[
1ce0: 63 6f 6e 73 74 20 74 72 75 65 5d 20 66 6f 72 20 const true] for
1cf0: 63 6c 69 65 6e 74 20 63 6f 6e 6e 65 63 74 69 6f client connectio
1d00: 6e 73 2e 20 53 74 61 72 74 69 6e 67 20 69 6e 20 ns. Starting in
1d10: 54 63 6c 54 4c 53 20 32 2e 30 2c 20 69 66 20 73 TclTLS 2.0, if s
1d20: 65 74 20 74 6f 0a 5b 63 6f 6e 73 74 20 66 61 6c et to.[const fal
1d30: 73 65 5d 20 61 6e 64 20 5b 6f 70 74 69 6f 6e 20 se] and [option
1d40: 2d 72 65 71 75 69 72 65 5d 20 69 73 20 5b 63 6f -require] is [co
1d50: 6e 73 74 20 74 72 75 65 5d 2c 20 74 68 65 6e 20 nst true], then
1d60: 74 68 69 73 20 77 69 6c 6c 20 62 65 0a 6f 76 65 this will be.ove
1d70: 72 72 69 64 64 65 6e 20 74 6f 20 5b 63 6f 6e 73 rridden to [cons
1d80: 74 20 74 72 75 65 5d 2e 20 53 65 65 20 5b 73 65 t true]. See [se
1d90: 63 74 72 65 66 20 22 43 65 72 74 69 66 69 63 61 ctref "Certifica
1da0: 74 65 20 56 61 6c 69 64 61 74 69 6f 6e 22 5d 20 te Validation"]
1db0: 66 6f 72 0a 6d 6f 72 65 20 64 65 74 61 69 6c 73 for.more details
1dc0: 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 72 65 71 ...[opt_def -req
1dd0: 75 69 72 65 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d uire [arg bool]]
1de0: 0a 52 65 71 75 69 72 65 20 61 20 76 61 6c 69 64 .Require a valid
1df0: 20 63 65 72 74 69 66 69 63 61 74 65 20 66 72 6f certificate fro
1e00: 6d 20 74 68 65 20 70 65 65 72 20 64 75 72 69 6e m the peer durin
1e10: 67 20 74 68 65 20 53 53 4c 20 68 61 6e 64 73 68 g the SSL handsh
1e20: 61 6b 65 2e 20 49 66 20 74 68 69 73 20 69 73 0a ake. If this is.
1e30: 73 65 74 20 74 6f 20 74 72 75 65 2c 20 74 68 65 set to true, the
1e40: 6e 20 5b 6f 70 74 69 6f 6e 20 2d 72 65 71 75 65 n [option -reque
1e50: 73 74 5d 20 6d 75 73 74 20 61 6c 73 6f 20 62 65 st] must also be
1e60: 20 73 65 74 20 74 6f 20 74 72 75 65 20 61 6e 64 set to true and
1e70: 20 61 20 65 69 74 68 65 72 0a 5b 6f 70 74 69 6f a either.[optio
1e80: 6e 20 2d 63 61 64 69 72 5d 2c 20 5b 6f 70 74 69 n -cadir], [opti
1e90: 6f 6e 20 2d 63 61 66 69 6c 65 5d 2c 20 5b 6f 70 on -cafile], [op
1ea0: 74 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 2c 20 tion -castore],
1eb0: 6f 72 20 61 20 70 6c 61 74 66 6f 72 6d 20 64 65 or a platform de
1ec0: 66 61 75 6c 74 0a 6d 75 73 74 20 62 65 20 70 72 fault.must be pr
1ed0: 6f 76 69 64 65 64 20 69 6e 20 6f 72 64 65 72 20 ovided in order
1ee0: 74 6f 20 76 61 6c 69 64 61 74 65 20 61 67 61 69 to validate agai
1ef0: 6e 73 74 2e 20 54 68 65 20 64 65 66 61 75 6c 74 nst. The default
1f00: 20 69 6e 20 54 63 6c 54 4c 53 20 31 2e 38 20 61 in TclTLS 1.8 a
1f10: 6e 64 0a 65 61 72 6c 69 65 72 20 76 65 72 73 69 nd.earlier versi
1f20: 6f 6e 73 20 69 73 20 5b 63 6f 6e 73 74 20 66 61 ons is [const fa
1f30: 6c 73 65 5d 20 73 69 6e 63 65 20 6e 6f 74 20 61 lse] since not a
1f40: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 20 68 61 76 ll platforms hav
1f50: 65 20 63 65 72 74 69 66 69 63 61 74 65 73 20 74 e certificates t
1f60: 6f 0a 76 61 6c 69 64 61 74 65 20 61 67 61 69 6e o.validate again
1f70: 73 74 20 69 6e 20 61 20 66 6f 72 6d 20 63 6f 6d st in a form com
1f80: 70 61 74 69 62 6c 65 20 77 69 74 68 20 4f 70 65 patible with Ope
1f90: 6e 53 53 4c 2e 20 53 74 61 72 74 69 6e 67 20 69 nSSL. Starting i
1fa0: 6e 20 54 63 6c 54 4c 53 20 32 2e 30 2c 0a 74 68 n TclTLS 2.0,.th
1fb0: 65 20 64 65 66 61 75 6c 74 20 69 73 20 5b 63 6f e default is [co
1fc0: 6e 73 74 20 74 72 75 65 5d 20 66 6f 72 20 63 6c nst true] for cl
1fd0: 69 65 6e 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 ient connections
1fe0: 2e 0a 53 65 65 20 5b 73 65 63 74 72 65 66 20 22 ..See [sectref "
1ff0: 43 65 72 74 69 66 69 63 61 74 65 20 56 61 6c 69 Certificate Vali
2000: 64 61 74 69 6f 6e 22 5d 20 66 6f 72 20 6d 6f 72 dation"] for mor
2010: 65 20 64 65 74 61 69 6c 73 2e 0a 0a 5b 6f 70 74 e details...[opt
2020: 5f 64 65 66 20 2d 73 65 63 75 72 69 74 79 5f 6c _def -security_l
2030: 65 76 65 6c 20 5b 61 72 67 20 69 6e 74 65 67 65 evel [arg intege
2040: 72 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 68 r]].Specifies th
2050: 65 20 73 65 63 75 72 69 74 79 20 6c 65 76 65 6c e security level
2060: 20 28 76 61 6c 75 65 20 66 72 6f 6d 20 30 20 74 (value from 0 t
2070: 6f 20 35 29 2e 20 54 68 65 20 73 65 63 75 72 69 o 5). The securi
2080: 74 79 20 6c 65 76 65 6c 20 61 66 66 65 63 74 73 ty level affects
2090: 0a 74 68 65 20 61 6c 6c 6f 77 65 64 20 63 69 70 .the allowed cip
20a0: 68 65 72 20 73 75 69 74 65 20 65 6e 63 72 79 70 her suite encryp
20b0: 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 73 2c tion algorithms,
20c0: 20 73 75 70 70 6f 72 74 65 64 20 45 43 43 20 63 supported ECC c
20d0: 75 72 76 65 73 2c 0a 73 75 70 70 6f 72 74 65 64 urves,.supported
20e0: 20 73 69 67 6e 61 74 75 72 65 20 61 6c 67 6f 72 signature algor
20f0: 69 74 68 6d 73 2c 20 44 48 20 70 61 72 61 6d 65 ithms, DH parame
2100: 74 65 72 20 73 69 7a 65 73 2c 20 63 65 72 74 69 ter sizes, certi
2110: 66 69 63 61 74 65 20 6b 65 79 20 73 69 7a 65 73 ficate key sizes
2120: 0a 61 6e 64 20 73 69 67 6e 61 74 75 72 65 20 61 .and signature a
2130: 6c 67 6f 72 69 74 68 6d 73 2e 20 54 68 65 20 64 lgorithms. The d
2140: 65 66 61 75 6c 74 20 69 73 20 31 20 70 72 69 6f efault is 1 prio
2150: 72 20 74 6f 20 4f 70 65 6e 53 53 4c 20 33 2e 32 r to OpenSSL 3.2
2160: 20 61 6e 64 20 32 0a 74 68 65 72 65 61 66 74 65 and 2.thereafte
2170: 72 2e 20 4c 65 76 65 6c 20 33 20 61 6e 64 20 68 r. Level 3 and h
2180: 69 67 68 65 72 20 64 69 73 61 62 6c 65 20 73 75 igher disable su
2190: 70 70 6f 72 74 20 66 6f 72 20 73 65 73 73 69 6f pport for sessio
21a0: 6e 20 74 69 63 6b 65 74 73 20 61 6e 64 0a 6f 6e n tickets and.on
21b0: 6c 79 20 61 63 63 65 70 74 20 63 69 70 68 65 72 ly accept cipher
21c0: 20 73 75 69 74 65 73 20 74 68 61 74 20 70 72 6f suites that pro
21d0: 76 69 64 65 20 66 6f 72 77 61 72 64 20 73 65 63 vide forward sec
21e0: 72 65 63 79 2e 0a 54 68 69 73 20 6f 70 74 69 6f recy..This optio
21f0: 6e 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c n is new for Tcl
2200: 54 4c 53 20 31 2e 38 2e 0a 0a 5b 6f 70 74 5f 64 TLS 1.8...[opt_d
2210: 65 66 20 2d 73 65 72 76 65 72 20 5b 61 72 67 20 ef -server [arg
2220: 62 6f 6f 6c 5d 5d 0a 53 70 65 63 69 66 69 65 73 bool]].Specifies
2230: 20 77 68 65 74 68 65 72 20 74 6f 20 61 63 74 20 whether to act
2240: 61 73 20 61 20 73 65 72 76 65 72 20 61 6e 64 20 as a server and
2250: 72 65 73 70 6f 6e 64 20 77 69 74 68 20 61 20 73 respond with a s
2260: 65 72 76 65 72 20 68 61 6e 64 73 68 61 6b 65 20 erver handshake
2270: 77 68 65 6e 20 61 0a 63 6c 69 65 6e 74 20 63 6f when a.client co
2280: 6e 6e 65 63 74 73 20 61 6e 64 20 70 72 6f 76 69 nnects and provi
2290: 64 65 73 20 61 20 63 6c 69 65 6e 74 20 68 61 6e des a client han
22a0: 64 73 68 61 6b 65 2e 20 54 68 65 20 64 65 66 61 dshake. The defa
22b0: 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 66 61 ult is [const fa
22c0: 6c 73 65 5d 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 lse]...[opt_def
22d0: 2d 73 65 72 76 65 72 6e 61 6d 65 20 5b 61 72 67 -servername [arg
22e0: 20 68 6f 73 74 6e 61 6d 65 5d 5d 0a 53 70 65 63 hostname]].Spec
22f0: 69 66 79 20 74 68 65 20 70 65 65 72 27 73 20 68 ify the peer's h
2300: 6f 73 74 6e 61 6d 65 2e 20 54 68 69 73 20 69 73 ostname. This is
2310: 20 75 73 65 64 20 74 6f 20 73 65 74 20 74 68 65 used to set the
2320: 20 54 4c 53 20 53 65 72 76 65 72 20 4e 61 6d 65 TLS Server Name
2330: 20 49 6e 64 69 63 61 74 69 6f 6e 0a 28 53 4e 49 Indication.(SNI
2340: 29 20 65 78 74 65 6e 73 69 6f 6e 2e 20 53 65 74 ) extension. Set
2350: 20 74 68 69 73 20 74 6f 20 74 68 65 20 65 78 70 this to the exp
2360: 65 63 74 65 64 20 73 65 72 76 65 72 6e 61 6d 65 ected servername
2370: 20 69 6e 20 74 68 65 20 73 65 72 76 65 72 27 73 in the server's
2380: 20 63 65 72 74 69 66 69 63 61 74 65 0a 6f 72 20 certificate.or
2390: 6f 6e 65 20 6f 66 20 74 68 65 20 53 75 62 6a 65 one of the Subje
23a0: 63 74 20 41 6c 74 65 72 6e 61 74 65 20 4e 61 6d ct Alternate Nam
23b0: 65 73 20 28 53 41 4e 29 2e 20 53 74 61 72 74 69 es (SAN). Starti
23c0: 6e 67 20 69 6e 20 54 63 6c 54 4c 53 20 32 2e 30 ng in TclTLS 2.0
23d0: 2c 20 74 68 69 73 20 77 69 6c 6c 0a 64 65 66 61 , this will.defa
23e0: 75 6c 74 20 74 6f 20 74 68 65 20 68 6f 73 74 20 ult to the host
23f0: 66 6f 72 20 74 68 65 20 5b 63 6d 64 20 74 6c 73 for the [cmd tls
2400: 3a 3a 73 6f 63 6b 65 74 5d 20 63 6f 6d 6d 61 6e ::socket] comman
2410: 64 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 73 65 d...[opt_def -se
2420: 73 73 69 6f 6e 5f 69 64 20 5b 61 72 67 20 62 69 ssion_id [arg bi
2430: 6e 61 72 79 5f 73 74 72 69 6e 67 5d 5d 0a 53 70 nary_string]].Sp
2440: 65 63 69 66 69 65 73 20 74 68 65 20 73 65 73 73 ecifies the sess
2450: 69 6f 6e 20 69 64 20 74 6f 20 72 65 73 75 6d 65 ion id to resume
2460: 20 61 20 73 65 73 73 69 6f 6e 2e 20 4e 6f 74 20 a session. Not
2470: 73 75 70 70 6f 72 74 65 64 20 79 65 74 2e 0a 54 supported yet..T
2480: 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 his option is ne
2490: 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 w for TclTLS 1.8
24a0: 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 73 73 6c ...[opt_def -ssl
24b0: 32 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 45 6e 2 [arg bool]].En
24c0: 61 62 6c 65 20 75 73 65 20 6f 66 20 53 53 4c 20 able use of SSL
24d0: 76 32 2e 54 68 65 20 64 65 66 61 75 6c 74 20 69 v2.The default i
24e0: 73 20 5b 63 6f 6e 73 74 20 66 61 6c 73 65 5d 2e s [const false].
24f0: 0a 4f 70 65 6e 53 53 4c 20 31 2e 31 2b 20 6e 6f .OpenSSL 1.1+ no
2500: 20 6c 6f 6e 67 65 72 20 73 75 70 70 6f 72 74 73 longer supports
2510: 20 53 53 4c 20 76 32 2c 20 73 6f 20 74 68 69 73 SSL v2, so this
2520: 20 6d 61 79 20 6e 6f 74 20 68 61 76 65 20 61 6e may not have an
2530: 79 20 65 66 66 65 63 74 2e 0a 53 65 65 20 74 68 y effect..See th
2540: 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 72 6f 74 e [cmd tls::prot
2550: 6f 63 6f 6c 73 5d 20 63 6f 6d 6d 61 6e 64 20 66 ocols] command f
2560: 6f 72 20 73 75 70 70 6f 72 74 65 64 20 70 72 6f or supported pro
2570: 74 6f 63 6f 6c 73 2e 0a 0a 5b 6f 70 74 5f 64 65 tocols...[opt_de
2580: 66 20 2d 73 73 6c 33 20 5b 61 72 67 20 62 6f 6f f -ssl3 [arg boo
2590: 6c 5d 5d 0a 45 6e 61 62 6c 65 20 75 73 65 20 6f l]].Enable use o
25a0: 66 20 53 53 4c 20 76 33 2e 20 54 68 65 20 64 65 f SSL v3. The de
25b0: 66 61 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 fault is [const
25c0: 66 61 6c 73 65 5d 2e 20 53 74 61 72 74 69 6e 67 false]. Starting
25d0: 20 69 6e 20 54 63 6c 54 4c 53 20 31 2e 38 2c 0a in TclTLS 1.8,.
25e0: 75 73 65 20 6f 66 20 53 53 4c 20 76 33 20 69 66 use of SSL v3 if
25f0: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
2600: 76 69 61 20 61 20 63 6f 6d 70 69 6c 65 20 74 69 via a compile ti
2610: 6d 65 20 6f 70 74 69 6f 6e 2e 0a 53 65 65 20 74 me option..See t
2620: 68 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 72 6f he [cmd tls::pro
2630: 74 6f 63 6f 6c 73 5d 20 63 6f 6d 6d 61 6e 64 20 tocols] command
2640: 66 6f 72 20 73 75 70 70 6f 72 74 65 64 20 70 72 for supported pr
2650: 6f 74 6f 63 6f 6c 73 2e 0a 0a 5b 6f 70 74 5f 64 otocols...[opt_d
2660: 65 66 20 2d 74 6c 73 31 20 5b 61 72 67 20 62 6f ef -tls1 [arg bo
2670: 6f 6c 5d 5d 0a 45 6e 61 62 6c 65 20 75 73 65 20 ol]].Enable use
2680: 6f 66 20 54 4c 53 20 76 31 2e 20 53 74 61 72 74 of TLS v1. Start
2690: 69 6e 67 20 69 6e 20 54 63 6c 54 4c 53 20 32 2e ing in TclTLS 2.
26a0: 30 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 69 0, the default i
26b0: 73 20 5b 63 6f 6e 73 74 20 66 61 6c 73 65 5d 2e s [const false].
26c0: 0a 4e 6f 74 65 3a 20 54 4c 53 20 31 2e 30 20 6e .Note: TLS 1.0 n
26d0: 65 65 64 73 20 53 48 41 31 20 74 6f 20 6f 70 65 eeds SHA1 to ope
26e0: 72 61 74 65 2c 20 77 68 69 63 68 20 69 73 20 6f rate, which is o
26f0: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e nly available in
2700: 20 73 65 63 75 72 69 74 79 20 6c 65 76 65 6c 0a security level.
2710: 30 20 66 6f 72 20 4f 70 65 6e 20 53 53 4c 20 33 0 for Open SSL 3
2720: 2e 30 2b 2e 20 53 65 65 20 74 68 65 20 5b 6f 70 .0+. See the [op
2730: 74 69 6f 6e 20 2d 73 65 63 75 72 69 74 79 5f 6c tion -security_l
2740: 65 76 65 6c 5d 20 6f 70 74 69 6f 6e 2e 0a 0a 5b evel] option...[
2750: 6f 70 74 5f 64 65 66 20 2d 74 6c 73 31 2e 31 20 opt_def -tls1.1
2760: 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 45 6e 61 62 [arg bool]].Enab
2770: 6c 65 20 75 73 65 20 6f 66 20 54 4c 53 20 76 31 le use of TLS v1
2780: 2e 31 2e 20 53 74 61 72 74 69 6e 67 20 69 6e 20 .1. Starting in
2790: 54 63 6c 54 4c 53 20 32 2e 30 2c 20 74 68 65 20 TclTLS 2.0, the
27a0: 64 65 66 61 75 6c 74 20 69 73 20 5b 63 6f 6e 73 default is [cons
27b0: 74 20 66 61 6c 73 65 5d 2e 0a 4e 6f 74 65 3a 20 t false]..Note:
27c0: 54 4c 53 20 31 2e 31 20 6e 65 65 64 73 20 53 48 TLS 1.1 needs SH
27d0: 41 31 20 74 6f 20 6f 70 65 72 61 74 65 2c 20 77 A1 to operate, w
27e0: 68 69 63 68 20 69 73 20 6f 6e 6c 79 20 61 76 61 hich is only ava
27f0: 69 6c 61 62 6c 65 20 69 6e 20 73 65 63 75 72 69 ilable in securi
2800: 74 79 20 6c 65 76 65 6c 0a 30 20 66 6f 72 20 4f ty level.0 for O
2810: 70 65 6e 20 53 53 4c 20 33 2e 30 2b 2e 20 53 65 pen SSL 3.0+. Se
2820: 65 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 73 e the [option -s
2830: 65 63 75 72 69 74 79 5f 6c 65 76 65 6c 5d 20 6f ecurity_level] o
2840: 70 74 69 6f 6e 2e 0a 0a 5b 6f 70 74 5f 64 65 66 ption...[opt_def
2850: 20 2d 74 6c 73 31 2e 32 20 5b 61 72 67 20 62 6f -tls1.2 [arg bo
2860: 6f 6c 5d 5d 0a 45 6e 61 62 6c 65 20 75 73 65 20 ol]].Enable use
2870: 6f 66 20 54 4c 53 20 76 31 2e 32 2e 20 54 68 65 of TLS v1.2. The
2880: 20 64 65 66 61 75 6c 74 20 69 73 20 5b 63 6f 6e default is [con
2890: 73 74 20 74 72 75 65 5d 2e 0a 0a 5b 6f 70 74 5f st true]...[opt_
28a0: 64 65 66 20 2d 74 6c 73 31 2e 33 20 5b 61 72 67 def -tls1.3 [arg
28b0: 20 62 6f 6f 6c 5d 5d 0a 45 6e 61 62 6c 65 20 75 bool]].Enable u
28c0: 73 65 20 6f 66 20 54 4c 53 20 76 31 2e 33 2e 20 se of TLS v1.3.
28d0: 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 5b The default is [
28e0: 63 6f 6e 73 74 20 74 72 75 65 5d 2e 20 54 68 69 const true]. Thi
28f0: 73 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 s is only availa
2900: 62 6c 65 0a 73 74 61 72 74 69 6e 67 20 77 69 74 ble.starting wit
2910: 68 20 4f 70 65 6e 53 53 4c 20 31 2e 31 2e 31 20 h OpenSSL 1.1.1
2920: 61 6e 64 20 54 63 6c 54 4c 53 20 31 2e 37 2e 0a and TclTLS 1.7..
2930: 0a 5b 6f 70 74 5f 64 65 66 20 2d 76 61 6c 69 64 .[opt_def -valid
2940: 61 74 65 63 6f 6d 6d 61 6e 64 20 5b 61 72 67 20 atecommand [arg
2950: 63 61 6c 6c 62 61 63 6b 5d 5d 0a 53 70 65 63 69 callback]].Speci
2960: 66 69 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 fies the callbac
2970: 6b 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 69 6e 76 k command to inv
2980: 6f 6b 65 20 74 6f 20 76 61 6c 69 64 61 74 65 20 oke to validate
2990: 74 68 65 20 70 65 65 72 20 63 65 72 74 69 66 69 the peer certifi
29a0: 63 61 74 65 73 0a 61 6e 64 20 6f 74 68 65 72 20 cates.and other
29b0: 63 6f 6e 66 69 67 20 69 6e 66 6f 20 64 75 72 69 config info duri
29c0: 6e 67 20 74 68 65 20 70 72 6f 74 6f 63 6f 6c 20 ng the protocol
29d0: 6e 65 67 6f 74 69 61 74 69 6f 6e 20 70 68 61 73 negotiation phas
29e0: 65 2e 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 e. This can be u
29f0: 73 65 64 0a 62 79 20 54 43 4c 20 73 63 72 69 70 sed.by TCL scrip
2a00: 74 73 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ts to perform th
2a10: 65 69 72 20 6f 77 6e 20 43 65 72 74 69 66 69 63 eir own Certific
2a20: 61 74 65 20 56 61 6c 69 64 61 74 69 6f 6e 20 74 ate Validation t
2a30: 6f 20 73 75 70 70 6c 65 6d 65 6e 74 20 74 68 65 o supplement the
2a40: 0a 64 65 66 61 75 6c 74 20 76 61 6c 69 64 61 74 .default validat
2a50: 69 6f 6e 20 70 72 6f 76 69 64 65 64 20 62 79 20 ion provided by
2a60: 4f 70 65 6e 53 53 4c 2e 20 54 68 65 20 73 63 72 OpenSSL. The scr
2a70: 69 70 74 20 6d 75 73 74 20 72 65 74 75 72 6e 20 ipt must return
2a80: 61 20 62 6f 6f 6c 65 61 6e 20 74 72 75 65 0a 74 a boolean true.t
2a90: 6f 20 63 6f 6e 74 69 6e 75 65 20 74 68 65 20 6e o continue the n
2aa0: 65 67 6f 74 69 61 74 69 6f 6e 2e 20 53 65 65 20 egotiation. See
2ab0: 5b 73 65 63 74 72 65 66 20 22 43 61 6c 6c 62 61 [sectref "Callba
2ac0: 63 6b 20 4f 70 74 69 6f 6e 73 22 5d 20 66 6f 72 ck Options"] for
2ad0: 20 6d 6f 72 65 20 69 6e 66 6f 2e 0a 54 68 69 73 more info..This
2ae0: 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 77 20 66 option is new f
2af0: 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a or TclTLS 1.8...
2b00: 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 63 61 6c [list_end]..[cal
2b10: 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a 75 6e 69 6d l [cmd tls::unim
2b20: 70 6f 72 74 5d 20 5b 61 72 67 20 63 68 61 6e 6e port] [arg chann
2b30: 65 6c 5d 5d 0a 0a 43 6f 6d 70 6c 69 6d 65 6e 74 el]]..Compliment
2b40: 20 74 6f 20 5b 63 6d 64 20 74 6c 73 3a 3a 69 6d to [cmd tls::im
2b50: 70 6f 72 74 5d 2e 20 55 73 65 64 20 74 6f 20 72 port]. Used to r
2b60: 65 6d 6f 76 65 20 74 68 65 20 74 6f 70 20 6c 65 emove the top le
2b70: 76 65 6c 20 73 74 61 63 6b 65 64 20 63 68 61 6e vel stacked chan
2b80: 6e 65 6c 0a 66 72 6f 6d 20 5b 61 72 67 20 63 68 nel.from [arg ch
2b90: 61 6e 6e 65 6c 5d 2e 20 54 68 69 73 20 75 6e 73 annel]. This uns
2ba0: 74 61 63 6b 73 20 74 68 65 20 65 6e 63 72 79 70 tacks the encryp
2bb0: 74 69 6f 6e 20 6f 66 20 61 20 72 65 67 75 6c 61 tion of a regula
2bc0: 72 20 54 43 4c 20 63 68 61 6e 6e 65 6c 2e 20 41 r TCL channel. A
2bd0: 6e 0a 65 72 72 6f 72 20 69 73 20 74 68 72 6f 77 n.error is throw
2be0: 6e 20 69 66 20 54 4c 53 20 69 73 20 6e 6f 74 20 n if TLS is not
2bf0: 74 68 65 20 74 6f 70 20 73 74 61 63 6b 65 64 20 the top stacked
2c00: 63 68 61 6e 6e 65 6c 20 74 79 70 65 2e 0a 0a 5b channel type...[
2c10: 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a 68 call [cmd tls::h
2c20: 61 6e 64 73 68 61 6b 65 5d 20 5b 61 72 67 20 63 andshake] [arg c
2c30: 68 61 6e 6e 65 6c 5d 5d 0a 0a 46 6f 72 63 65 73 hannel]]..Forces
2c40: 20 74 68 65 20 54 4c 53 20 6e 65 67 6f 74 69 61 the TLS negotia
2c50: 74 69 6f 6e 20 68 61 6e 64 73 68 61 6b 65 20 74 tion handshake t
2c60: 6f 20 74 61 6b 65 20 70 6c 61 63 65 20 69 6d 6d o take place imm
2c70: 65 64 69 61 74 65 6c 79 2c 20 61 6e 64 20 72 65 ediately, and re
2c80: 74 75 72 6e 73 20 30 0a 69 66 20 68 61 6e 64 73 turns 0.if hands
2c90: 68 61 6b 65 20 69 73 20 73 74 69 6c 6c 20 69 6e hake is still in
2ca0: 20 70 72 6f 67 72 65 73 73 20 28 6e 6f 6e 2d 62 progress (non-b
2cb0: 6c 6f 63 6b 69 6e 67 29 2c 20 6f 72 20 31 20 69 locking), or 1 i
2cc0: 66 20 74 68 65 20 68 61 6e 64 73 68 61 6b 65 20 f the handshake
2cd0: 77 61 73 0a 73 75 63 63 65 73 73 66 75 6c 2e 20 was.successful.
2ce0: 49 66 20 74 68 65 20 68 61 6e 64 73 68 61 6b 65 If the handshake
2cf0: 20 66 61 69 6c 65 64 2c 20 61 6e 20 65 72 72 6f failed, an erro
2d00: 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e r will be return
2d10: 65 64 2e 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 ed...[call [cmd
2d20: 74 6c 73 3a 3a 73 74 61 74 75 73 5d 20 5b 6f 70 tls::status] [op
2d30: 74 20 5b 6f 70 74 69 6f 6e 20 2d 6c 6f 63 61 6c t [option -local
2d40: 5d 5d 20 5b 61 72 67 20 63 68 61 6e 6e 65 6c 5d ]] [arg channel]
2d50: 5d 0a 0a 52 65 74 75 72 6e 73 20 74 68 65 20 63 ]..Returns the c
2d60: 75 72 72 65 6e 74 20 73 74 61 74 75 73 20 6f 66 urrent status of
2d70: 20 61 6e 20 53 53 4c 20 63 68 61 6e 6e 65 6c 2e an SSL channel.
2d80: 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 The result is a
2d90: 20 6c 69 73 74 20 6f 66 20 6b 65 79 2d 76 61 6c list of key-val
2da0: 75 65 0a 70 61 69 72 73 20 64 65 73 63 72 69 62 ue.pairs describ
2db0: 69 6e 67 20 74 68 65 20 53 53 4c 2c 20 63 65 72 ing the SSL, cer
2dc0: 74 69 66 69 63 61 74 65 2c 20 61 6e 64 20 63 65 tificate, and ce
2dd0: 72 74 69 66 69 63 61 74 65 20 76 65 72 69 66 69 rtificate verifi
2de0: 63 61 74 69 6f 6e 20 73 74 61 74 75 73 2e 20 49 cation status. I
2df0: 66 0a 74 68 65 20 53 53 4c 20 68 61 6e 64 73 68 f.the SSL handsh
2e00: 61 6b 65 20 68 61 73 20 6e 6f 74 20 79 65 74 20 ake has not yet
2e10: 63 6f 6d 70 6c 65 74 65 64 2c 20 61 6e 20 65 6d completed, an em
2e20: 70 74 79 20 6c 69 73 74 20 69 73 20 72 65 74 75 pty list is retu
2e30: 72 6e 65 64 2e 20 49 66 20 74 68 65 0a 5b 6f 70 rned. If the.[op
2e40: 74 69 6f 6e 20 2d 6c 6f 63 61 6c 5d 20 6f 70 74 tion -local] opt
2e50: 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 ion is specified
2e60: 2c 20 74 68 65 6e 20 74 68 65 20 6c 6f 63 61 6c , then the local
2e70: 20 63 65 72 74 69 66 69 63 61 74 65 20 69 73 20 certificate is
2e80: 75 73 65 64 2e 20 52 65 74 75 72 6e 65 64 0a 76 used. Returned.v
2e90: 61 6c 75 65 73 20 69 6e 63 6c 75 64 65 3a 0a 0a alues include:..
2ea0: 5b 70 61 72 61 5d 0a 0a 53 53 4c 20 53 74 61 74 [para]..SSL Stat
2eb0: 75 73 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e 20 us..[list_begin
2ec0: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a 5b 64 definitions]..[d
2ed0: 65 66 20 22 5b 76 61 72 20 61 6c 70 6e 5d 20 5b ef "[var alpn] [
2ee0: 61 72 67 20 70 72 6f 74 6f 63 6f 6c 5d 22 5d 0a arg protocol]"].
2ef0: 54 68 65 20 70 72 6f 74 6f 63 6f 6c 20 73 65 6c The protocol sel
2f00: 65 63 74 65 64 20 61 66 74 65 72 20 41 70 70 6c ected after Appl
2f10: 69 63 61 74 69 6f 6e 2d 4c 61 79 65 72 20 50 72 ication-Layer Pr
2f20: 6f 74 6f 63 6f 6c 20 4e 65 67 6f 74 69 61 74 69 otocol Negotiati
2f30: 6f 6e 20 28 41 4c 50 4e 29 2e 0a 54 68 69 73 20 on (ALPN)..This
2f40: 76 61 6c 75 65 20 69 73 20 6e 65 77 20 66 6f 72 value is new for
2f50: 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 TclTLS 1.8...[d
2f60: 65 66 20 22 5b 76 61 72 20 63 69 70 68 65 72 5d ef "[var cipher]
2f70: 20 5b 61 72 67 20 63 69 70 68 65 72 5d 22 5d 0a [arg cipher]"].
2f80: 54 68 65 20 63 75 72 72 65 6e 74 20 63 69 70 68 The current ciph
2f90: 65 72 20 69 6e 20 75 73 65 20 66 6f 72 20 74 68 er in use for th
2fa0: 65 20 73 65 73 73 69 6f 6e 2e 0a 0a 5b 64 65 66 e session...[def
2fb0: 20 22 5b 76 61 72 20 70 65 65 72 6e 61 6d 65 5d "[var peername]
2fc0: 20 5b 61 72 67 20 6e 61 6d 65 5d 22 5d 0a 54 68 [arg name]"].Th
2fd0: 65 20 70 65 65 72 6e 61 6d 65 20 66 72 6f 6d 20 e peername from
2fe0: 74 68 65 20 63 65 72 74 69 66 69 63 61 74 65 2e the certificate.
2ff0: 0a 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e .This value is n
3000: 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e ew for TclTLS 1.
3010: 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 70 8...[def "[var p
3020: 72 6f 74 6f 63 6f 6c 5d 20 5b 61 72 67 20 76 65 rotocol] [arg ve
3030: 72 73 69 6f 6e 5d 22 5d 0a 54 68 65 20 70 72 6f rsion]"].The pro
3040: 74 6f 63 6f 6c 20 76 65 72 73 69 6f 6e 20 75 73 tocol version us
3050: 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
3060: 63 74 69 6f 6e 3a 20 53 53 4c 32 2c 20 53 53 4c ction: SSL2, SSL
3070: 33 2c 20 54 4c 53 31 2c 20 54 4c 53 31 2e 31 2c 3, TLS1, TLS1.1,
3080: 20 54 4c 53 31 2e 32 2c 0a 54 4c 53 31 2e 33 2c TLS1.2,.TLS1.3,
3090: 20 6f 72 20 75 6e 6b 6e 6f 77 6e 2e 20 54 68 69 or unknown. Thi
30a0: 73 20 76 61 6c 75 65 20 69 73 20 6e 65 77 20 66 s value is new f
30b0: 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a or TclTLS 1.8...
30c0: 5b 64 65 66 20 22 5b 76 61 72 20 73 62 69 74 73 [def "[var sbits
30d0: 5d 20 5b 61 72 67 20 6e 5d 22 5d 0a 54 68 65 20 ] [arg n]"].The
30e0: 6e 75 6d 62 65 72 20 6f 66 20 62 69 74 73 20 75 number of bits u
30f0: 73 65 64 20 66 6f 72 20 74 68 65 20 73 65 73 73 sed for the sess
3100: 69 6f 6e 20 6b 65 79 2e 0a 0a 5b 64 65 66 20 22 ion key...[def "
3110: 5b 76 61 72 20 73 69 67 6e 61 74 75 72 65 48 61 [var signatureHa
3120: 73 68 41 6c 67 6f 72 69 74 68 6d 5d 20 5b 61 72 shAlgorithm] [ar
3130: 67 20 61 6c 67 6f 72 69 74 68 6d 5d 22 5d 0a 54 g algorithm]"].T
3140: 68 65 20 73 69 67 6e 61 74 75 72 65 20 68 61 73 he signature has
3150: 68 20 61 6c 67 6f 72 69 74 68 6d 2e 0a 54 68 69 h algorithm..Thi
3160: 73 20 76 61 6c 75 65 20 69 73 20 6e 65 77 20 66 s value is new f
3170: 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a or TclTLS 1.8...
3180: 5b 64 65 66 20 22 5b 76 61 72 20 73 69 67 6e 61 [def "[var signa
3190: 74 75 72 65 54 79 70 65 5d 20 5b 61 72 67 20 74 tureType] [arg t
31a0: 79 70 65 5d 22 5d 0a 54 68 65 20 73 69 67 6e 61 ype]"].The signa
31b0: 74 75 72 65 20 74 79 70 65 20 76 61 6c 75 65 2e ture type value.
31c0: 0a 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e .This value is n
31d0: 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e ew for TclTLS 1.
31e0: 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 76 8...[def "[var v
31f0: 65 72 69 66 79 44 65 70 74 68 5d 20 5b 61 72 67 erifyDepth] [arg
3200: 20 6e 5d 22 5d 0a 4d 61 78 69 6d 75 6d 20 64 65 n]"].Maximum de
3210: 70 74 68 20 66 6f 72 20 74 68 65 20 63 65 72 74 pth for the cert
3220: 69 66 69 63 61 74 65 20 63 68 61 69 6e 20 76 65 ificate chain ve
3230: 72 69 66 69 63 61 74 69 6f 6e 2e 20 44 65 66 61 rification. Defa
3240: 75 6c 74 20 69 73 20 2d 31 2c 20 74 6f 20 63 68 ult is -1, to ch
3250: 65 63 6b 20 61 6c 6c 2e 0a 54 68 69 73 20 76 61 eck all..This va
3260: 6c 75 65 20 69 73 20 6e 65 77 20 66 6f 72 20 54 lue is new for T
3270: 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 66 clTLS 1.8...[def
3280: 20 22 5b 76 61 72 20 76 65 72 69 66 79 4d 6f 64 "[var verifyMod
3290: 65 5d 20 5b 61 72 67 20 6c 69 73 74 5d 22 5d 0a e] [arg list]"].
32a0: 4c 69 73 74 20 6f 66 20 63 65 72 74 69 66 69 63 List of certific
32b0: 61 74 65 20 76 65 72 69 66 69 63 61 74 69 6f 6e ate verification
32c0: 20 6d 6f 64 65 73 2e 0a 54 68 69 73 20 76 61 6c modes..This val
32d0: 75 65 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 ue is new for Tc
32e0: 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 lTLS 1.8...[def
32f0: 22 5b 76 61 72 20 76 65 72 69 66 79 52 65 73 75 "[var verifyResu
3300: 6c 74 5d 20 5b 61 72 67 20 72 65 73 75 6c 74 5d lt] [arg result]
3310: 22 5d 0a 43 65 72 74 69 66 69 63 61 74 65 20 76 "].Certificate v
3320: 65 72 69 66 69 63 61 74 69 6f 6e 20 72 65 73 75 erification resu
3330: 6c 74 2e 0a 54 68 69 73 20 76 61 6c 75 65 20 69 lt..This value i
3340: 73 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 s new for TclTLS
3350: 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 1.8...[def "[va
3360: 72 20 63 61 5f 6e 61 6d 65 73 5d 20 5b 61 72 67 r ca_names] [arg
3370: 20 6c 69 73 74 5d 22 5d 0a 4c 69 73 74 20 6f 66 list]"].List of
3380: 20 74 68 65 20 43 65 72 74 69 66 69 63 61 74 65 the Certificate
3390: 20 41 75 74 68 6f 72 69 74 69 65 73 20 75 73 65 Authorities use
33a0: 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 d to create the
33b0: 63 65 72 74 69 66 69 63 61 74 65 2e 0a 54 68 69 certificate..Thi
33c0: 73 20 76 61 6c 75 65 20 69 73 20 6e 65 77 20 66 s value is new f
33d0: 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a or TclTLS 1.8...
33e0: 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 43 65 72 74 [list_end]..Cert
33f0: 69 66 69 63 61 74 65 20 53 74 61 74 75 73 0a 0a ificate Status..
3400: 5b 6c 69 73 74 5f 62 65 67 69 6e 20 64 65 66 69 [list_begin defi
3410: 6e 69 74 69 6f 6e 73 5d 0a 0a 5b 64 65 66 20 22 nitions]..[def "
3420: 5b 76 61 72 20 61 6c 6c 5d 20 5b 61 72 67 20 73 [var all] [arg s
3430: 74 72 69 6e 67 5d 22 5d 0a 44 75 6d 70 20 6f 66 tring]"].Dump of
3440: 20 61 6c 6c 20 63 65 72 74 69 66 69 63 61 74 65 all certificate
3450: 20 69 6e 66 6f 2e 0a 54 68 69 73 20 76 61 6c 75 info..This valu
3460: 65 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c e is new for Tcl
3470: 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 TLS 1.8...[def "
3480: 5b 76 61 72 20 76 65 72 73 69 6f 6e 5d 20 5b 61 [var version] [a
3490: 72 67 20 76 61 6c 75 65 5d 22 5d 0a 54 68 65 20 rg value]"].The
34a0: 63 65 72 74 69 66 69 63 61 74 65 20 76 65 72 73 certificate vers
34b0: 69 6f 6e 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 ion...[def "[var
34c0: 20 73 65 72 69 61 6c 4e 75 6d 62 65 72 5d 20 5b serialNumber] [
34d0: 61 72 67 20 73 74 72 69 6e 67 5d 22 5d 0a 54 68 arg string]"].Th
34e0: 65 20 73 65 72 69 61 6c 20 6e 75 6d 62 65 72 20 e serial number
34f0: 6f 66 20 74 68 65 20 63 65 72 74 69 66 69 63 61 of the certifica
3500: 74 65 20 61 73 20 61 20 68 65 78 20 73 74 72 69 te as a hex stri
3510: 6e 67 2e 0a 54 68 69 73 20 76 61 6c 75 65 20 77 ng..This value w
3520: 61 73 20 63 68 61 6e 67 65 64 20 66 72 6f 6d 20 as changed from
3530: 73 65 72 69 61 6c 20 69 6e 20 54 63 6c 54 4c 53 serial in TclTLS
3540: 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 1.8...[def "[va
3550: 72 20 73 69 67 6e 61 74 75 72 65 5d 20 5b 61 72 r signature] [ar
3560: 67 20 61 6c 67 6f 72 69 74 68 6d 5d 22 5d 0a 43 g algorithm]"].C
3570: 69 70 68 65 72 20 61 6c 67 6f 72 69 74 68 6d 20 ipher algorithm
3580: 75 73 65 64 20 66 6f 72 20 63 65 72 74 69 66 69 used for certifi
3590: 63 61 74 65 20 73 69 67 6e 61 74 75 72 65 2e 0a cate signature..
35a0: 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e 65 This value is ne
35b0: 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 w for TclTLS 1.8
35c0: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 69 73 ...[def "[var is
35d0: 73 75 65 72 5d 20 5b 61 72 67 20 73 74 72 69 6e suer] [arg strin
35e0: 67 5d 22 5d 0a 54 68 65 20 64 69 73 74 69 6e 67 g]"].The disting
35f0: 75 69 73 68 65 64 20 6e 61 6d 65 20 28 44 4e 29 uished name (DN)
3600: 20 6f 66 20 74 68 65 20 63 65 72 74 69 66 69 63 of the certific
3610: 61 74 65 20 69 73 73 75 65 72 2e 0a 0a 5b 64 65 ate issuer...[de
3620: 66 20 22 5b 76 61 72 20 6e 6f 74 42 65 66 6f 72 f "[var notBefor
3630: 65 5d 20 5b 61 72 67 20 64 61 74 65 5d 22 5d 0a e] [arg date]"].
3640: 54 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 64 61 The beginning da
3650: 74 65 20 6f 66 20 74 68 65 20 63 65 72 74 69 66 te of the certif
3660: 69 63 61 74 65 20 76 61 6c 69 64 69 74 79 2e 0a icate validity..
3670: 0a 5b 64 65 66 20 22 5b 76 61 72 20 6e 6f 74 41 .[def "[var notA
3680: 66 74 65 72 5d 20 5b 61 72 67 20 64 61 74 65 5d fter] [arg date]
3690: 22 5d 0a 54 68 65 20 65 78 70 69 72 61 74 69 6f "].The expiratio
36a0: 6e 20 64 61 74 65 20 6f 66 20 74 68 65 20 63 65 n date of the ce
36b0: 72 74 69 66 69 63 61 74 65 20 76 61 6c 69 64 69 rtificate validi
36c0: 74 79 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 ty...[def "[var
36d0: 73 75 62 6a 65 63 74 5d 20 5b 61 72 67 20 73 74 subject] [arg st
36e0: 72 69 6e 67 5d 22 5d 0a 54 68 65 20 64 69 73 74 ring]"].The dist
36f0: 69 6e 67 75 69 73 68 65 64 20 6e 61 6d 65 20 28 inguished name (
3700: 44 4e 29 20 6f 66 20 74 68 65 20 63 65 72 74 69 DN) of the certi
3710: 66 69 63 61 74 65 20 73 75 62 6a 65 63 74 2e 20 ficate subject.
3720: 46 69 65 6c 64 73 20 69 6e 63 6c 75 64 65 3a 20 Fields include:
3730: 43 6f 6d 6d 6f 6e 0a 4e 61 6d 65 20 28 43 4e 29 Common.Name (CN)
3740: 2c 20 4f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 28 , Organization (
3750: 4f 29 2c 20 4c 6f 63 61 6c 69 74 79 20 6f 72 20 O), Locality or
3760: 43 69 74 79 20 28 4c 29 2c 20 53 74 61 74 65 20 City (L), State
3770: 6f 72 20 50 72 6f 76 69 6e 63 65 20 28 53 29 2c or Province (S),
3780: 20 61 6e 64 0a 43 6f 75 6e 74 72 79 20 4e 61 6d and.Country Nam
3790: 65 20 28 43 29 2e 0a 0a 5b 64 65 66 20 22 5b 76 e (C)...[def "[v
37a0: 61 72 20 69 73 73 75 65 72 55 6e 69 71 75 65 49 ar issuerUniqueI
37b0: 44 5d 20 5b 61 72 67 20 73 74 72 69 6e 67 5d 22 D] [arg string]"
37c0: 5d 0a 54 68 65 20 69 73 73 75 65 72 20 75 6e 69 ].The issuer uni
37d0: 71 75 65 20 69 64 2e 0a 54 68 69 73 20 76 61 6c que id..This val
37e0: 75 65 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 ue is new for Tc
37f0: 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 lTLS 1.8...[def
3800: 22 5b 76 61 72 20 73 75 62 6a 65 63 74 55 6e 69 "[var subjectUni
3810: 71 75 65 49 44 5d 20 5b 61 72 67 20 73 74 72 69 queID] [arg stri
3820: 6e 67 5d 22 5d 0a 54 68 65 20 73 75 62 6a 65 63 ng]"].The subjec
3830: 74 20 75 6e 69 71 75 65 20 69 64 2e 0a 54 68 69 t unique id..Thi
3840: 73 20 76 61 6c 75 65 20 69 73 20 6e 65 77 20 66 s value is new f
3850: 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a or TclTLS 1.8...
3860: 5b 64 65 66 20 22 5b 76 61 72 20 6e 75 6d 5f 65 [def "[var num_e
3870: 78 74 65 6e 73 69 6f 6e 73 5d 20 5b 61 72 67 20 xtensions] [arg
3880: 6e 5d 22 5d 0a 4e 75 6d 62 65 72 20 6f 66 20 63 n]"].Number of c
3890: 65 72 74 69 66 69 63 61 74 65 20 65 78 74 65 6e ertificate exten
38a0: 73 69 6f 6e 73 2e 0a 54 68 69 73 20 76 61 6c 75 sions..This valu
38b0: 65 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c e is new for Tcl
38c0: 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 TLS 1.8...[def "
38d0: 5b 76 61 72 20 65 78 74 65 6e 73 69 6f 6e 73 5d [var extensions]
38e0: 20 5b 61 72 67 20 6c 69 73 74 5d 22 5d 0a 4c 69 [arg list]"].Li
38f0: 73 74 20 6f 66 20 63 65 72 74 69 66 69 63 61 74 st of certificat
3900: 65 20 65 78 74 65 6e 73 69 6f 6e 20 6e 61 6d 65 e extension name
3910: 73 2e 0a 54 68 69 73 20 76 61 6c 75 65 20 69 73 s..This value is
3920: 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 new for TclTLS
3930: 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 1.8...[def "[var
3940: 20 61 75 74 68 6f 72 69 74 79 4b 65 79 49 64 65 authorityKeyIde
3950: 6e 74 69 66 69 65 72 5d 20 5b 61 72 67 20 73 74 ntifier] [arg st
3960: 72 69 6e 67 5d 22 5d 0a 41 75 74 68 6f 72 69 74 ring]"].Authorit
3970: 79 20 4b 65 79 20 49 64 65 6e 74 69 66 69 65 72 y Key Identifier
3980: 20 28 41 4b 49 29 20 6f 66 20 74 68 65 20 49 73 (AKI) of the Is
3990: 73 75 69 6e 67 20 43 41 20 63 65 72 74 69 66 69 suing CA certifi
39a0: 63 61 74 65 20 74 68 61 74 20 73 69 67 6e 65 64 cate that signed
39b0: 20 74 68 65 0a 53 53 4c 20 63 65 72 74 69 66 69 the.SSL certifi
39c0: 63 61 74 65 20 61 73 20 61 20 68 65 78 20 73 74 cate as a hex st
39d0: 72 69 6e 67 2e 20 54 68 69 73 20 76 61 6c 75 65 ring. This value
39e0: 20 6d 61 74 63 68 65 73 20 74 68 65 20 53 4b 49 matches the SKI
39f0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 49 6e value of the.In
3a00: 74 65 72 6d 65 64 69 61 74 65 20 43 41 20 63 65 termediate CA ce
3a10: 72 74 69 66 69 63 61 74 65 2e 0a 54 68 69 73 20 rtificate..This
3a20: 76 61 6c 75 65 20 69 73 20 6e 65 77 20 66 6f 72 value is new for
3a30: 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 TclTLS 1.8...[d
3a40: 65 66 20 22 5b 76 61 72 20 73 75 62 6a 65 63 74 ef "[var subject
3a50: 4b 65 79 49 64 65 6e 74 69 66 69 65 72 5d 20 5b KeyIdentifier] [
3a60: 61 72 67 20 73 74 72 69 6e 67 5d 22 5d 0a 53 75 arg string]"].Su
3a70: 62 6a 65 63 74 20 4b 65 79 20 49 64 65 6e 74 69 bject Key Identi
3a80: 66 69 65 72 20 28 53 4b 49 29 20 68 61 73 68 20 fier (SKI) hash
3a90: 6f 66 20 74 68 65 20 70 75 62 6c 69 63 20 6b 65 of the public ke
3aa0: 79 20 69 6e 73 69 64 65 20 74 68 65 20 63 65 72 y inside the cer
3ab0: 74 69 66 69 63 61 74 65 20 61 73 20 61 0a 68 65 tificate as a.he
3ac0: 78 20 73 74 72 69 6e 67 2e 20 55 73 65 64 20 74 x string. Used t
3ad0: 6f 20 69 64 65 6e 74 69 66 79 20 63 65 72 74 69 o identify certi
3ae0: 66 69 63 61 74 65 73 20 74 68 61 74 20 63 6f 6e ficates that con
3af0: 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
3b00: 72 20 70 75 62 6c 69 63 20 6b 65 79 2e 0a 54 68 r public key..Th
3b10: 69 73 20 76 61 6c 75 65 20 69 73 20 6e 65 77 20 is value is new
3b20: 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a for TclTLS 1.8..
3b30: 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 75 62 6a .[def "[var subj
3b40: 65 63 74 41 6c 74 4e 61 6d 65 5d 20 5b 61 72 67 ectAltName] [arg
3b50: 20 6c 69 73 74 5d 22 5d 0a 4c 69 73 74 20 6f 66 list]"].List of
3b60: 20 61 6c 6c 20 6f 66 20 74 68 65 20 53 75 62 6a all of the Subj
3b70: 65 63 74 20 41 6c 74 65 72 6e 61 74 69 76 65 20 ect Alternative
3b80: 4e 61 6d 65 73 20 28 53 41 4e 29 20 69 6e 63 6c Names (SAN) incl
3b90: 75 64 69 6e 67 20 64 6f 6d 61 69 6e 20 6e 61 6d uding domain nam
3ba0: 65 73 2c 20 73 75 62 0a 64 6f 6d 61 69 6e 73 2c es, sub.domains,
3bb0: 20 61 6e 64 20 49 50 20 61 64 64 72 65 73 73 65 and IP addresse
3bc0: 73 20 74 68 61 74 20 61 72 65 20 73 65 63 75 72 s that are secur
3bd0: 65 64 20 62 79 20 74 68 65 20 63 65 72 74 69 66 ed by the certif
3be0: 69 63 61 74 65 2e 0a 54 68 69 73 20 76 61 6c 75 icate..This valu
3bf0: 65 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c e is new for Tcl
3c00: 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 TLS 1.8...[def "
3c10: 5b 76 61 72 20 6f 63 73 70 5d 20 5b 61 72 67 20 [var ocsp] [arg
3c20: 6c 69 73 74 5d 22 5d 0a 4c 69 73 74 20 6f 66 20 list]"].List of
3c30: 61 6c 6c 20 4f 6e 6c 69 6e 65 20 43 65 72 74 69 all Online Certi
3c40: 66 69 63 61 74 65 20 53 74 61 74 75 73 20 50 72 ficate Status Pr
3c50: 6f 74 6f 63 6f 6c 20 28 4f 43 53 50 29 20 55 52 otocol (OCSP) UR
3c60: 4c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 Ls that can be u
3c70: 73 65 64 20 74 6f 0a 63 68 65 63 6b 20 74 68 65 sed to.check the
3c80: 20 76 61 6c 69 64 69 74 79 20 6f 66 20 74 68 69 validity of thi
3c90: 73 20 63 65 72 74 69 66 69 63 61 74 65 2e 0a 54 s certificate..T
3ca0: 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e 65 77 his value is new
3cb0: 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e for TclTLS 1.8.
3cc0: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 63 65 72 ..[def "[var cer
3cd0: 74 69 66 69 63 61 74 65 5d 20 5b 61 72 67 20 63 tificate] [arg c
3ce0: 65 72 74 5d 22 5d 0a 54 68 65 20 50 45 4d 20 65 ert]"].The PEM e
3cf0: 6e 63 6f 64 65 64 20 63 65 72 74 69 66 69 63 61 ncoded certifica
3d00: 74 65 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 te...[def "[var
3d10: 73 69 67 6e 61 74 75 72 65 41 6c 67 6f 72 69 74 signatureAlgorit
3d20: 68 6d 5d 20 5b 61 72 67 20 61 6c 67 6f 72 69 74 hm] [arg algorit
3d30: 68 6d 5d 22 5d 0a 43 69 70 68 65 72 20 61 6c 67 hm]"].Cipher alg
3d40: 6f 72 69 74 68 6d 20 75 73 65 64 20 66 6f 72 20 orithm used for
3d50: 74 68 65 20 63 65 72 74 69 66 69 63 61 74 65 20 the certificate
3d60: 73 69 67 6e 61 74 75 72 65 2e 0a 54 68 69 73 20 signature..This
3d70: 76 61 6c 75 65 20 69 73 20 6e 65 77 20 66 6f 72 value is new for
3d80: 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 TclTLS 1.8...[d
3d90: 65 66 20 22 5b 76 61 72 20 73 69 67 6e 61 74 75 ef "[var signatu
3da0: 72 65 56 61 6c 75 65 5d 20 5b 61 72 67 20 73 74 reValue] [arg st
3db0: 72 69 6e 67 5d 22 5d 0a 43 65 72 74 69 66 69 63 ring]"].Certific
3dc0: 61 74 65 20 73 69 67 6e 61 74 75 72 65 20 61 73 ate signature as
3dd0: 20 61 20 68 65 78 20 73 74 72 69 6e 67 2e 0a 54 a hex string..T
3de0: 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e 65 77 his value is new
3df0: 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e for TclTLS 1.8.
3e00: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 69 67 ..[def "[var sig
3e10: 6e 61 74 75 72 65 44 69 67 65 73 74 5d 20 5b 61 natureDigest] [a
3e20: 72 67 20 76 65 72 73 69 6f 6e 5d 22 5d 0a 43 65 rg version]"].Ce
3e30: 72 74 69 66 69 63 61 74 65 20 73 69 67 6e 69 6e rtificate signin
3e40: 67 20 64 69 67 65 73 74 20 61 73 20 61 20 68 65 g digest as a he
3e50: 78 20 73 74 72 69 6e 67 2e 0a 54 68 69 73 20 76 x string..This v
3e60: 61 6c 75 65 20 69 73 20 6e 65 77 20 66 6f 72 20 alue is new for
3e70: 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 TclTLS 1.8...[de
3e80: 66 20 22 5b 76 61 72 20 70 75 62 6c 69 63 4b 65 f "[var publicKe
3e90: 79 41 6c 67 6f 72 69 74 68 6d 5d 20 5b 61 72 67 yAlgorithm] [arg
3ea0: 20 61 6c 67 6f 72 69 74 68 6d 5d 22 5d 0a 43 65 algorithm]"].Ce
3eb0: 72 74 69 66 69 63 61 74 65 20 73 69 67 6e 61 74 rtificate signat
3ec0: 75 72 65 20 70 75 62 6c 69 63 20 6b 65 79 20 61 ure public key a
3ed0: 6c 67 6f 72 69 74 68 6d 2e 0a 54 68 69 73 20 76 lgorithm..This v
3ee0: 61 6c 75 65 20 69 73 20 6e 65 77 20 66 6f 72 20 alue is new for
3ef0: 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 TclTLS 1.8...[de
3f00: 66 20 22 5b 76 61 72 20 70 75 62 6c 69 63 4b 65 f "[var publicKe
3f10: 79 5d 20 5b 61 72 67 20 73 74 72 69 6e 67 5d 22 y] [arg string]"
3f20: 5d 0a 43 65 72 74 69 66 69 63 61 74 65 20 73 69 ].Certificate si
3f30: 67 6e 61 74 75 72 65 20 70 75 62 6c 69 63 20 6b gnature public k
3f40: 65 79 20 61 73 20 61 20 68 65 78 20 73 74 72 69 ey as a hex stri
3f50: 6e 67 2e 0a 54 68 69 73 20 76 61 6c 75 65 20 69 ng..This value i
3f60: 73 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 s new for TclTLS
3f70: 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 1.8...[def "[va
3f80: 72 20 62 69 74 73 5d 20 5b 61 72 67 20 6e 5d 22 r bits] [arg n]"
3f90: 5d 0a 4e 75 6d 62 65 72 20 6f 66 20 62 69 74 73 ].Number of bits
3fa0: 20 75 73 65 64 20 66 6f 72 20 63 65 72 74 69 66 used for certif
3fb0: 69 63 61 74 65 20 73 69 67 6e 61 74 75 72 65 20 icate signature
3fc0: 6b 65 79 2e 0a 54 68 69 73 20 76 61 6c 75 65 20 key..This value
3fd0: 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c is new for TclTL
3fe0: 53 20 31 2e 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 S 1.8...[def "[v
3ff0: 61 72 20 73 65 6c 66 5f 73 69 67 6e 65 64 5d 20 ar self_signed]
4000: 5b 61 72 67 20 62 6f 6f 6c 65 61 6e 5d 22 5d 0a [arg boolean]"].
4010: 57 68 65 74 68 65 72 20 74 68 65 20 63 65 72 74 Whether the cert
4020: 69 66 69 63 61 74 65 20 73 69 67 6e 61 74 75 72 ificate signatur
4030: 65 20 69 73 20 73 65 6c 66 20 73 69 67 6e 65 64 e is self signed
4040: 2e 0a 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 ..This value is
4050: 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 new for TclTLS 1
4060: 2e 38 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 .8...[def "[var
4070: 73 68 61 31 5f 68 61 73 68 5d 20 5b 61 72 67 20 sha1_hash] [arg
4080: 68 61 73 68 5d 22 5d 0a 54 68 65 20 53 48 41 31 hash]"].The SHA1
4090: 20 68 61 73 68 20 6f 66 20 74 68 65 20 63 65 72 hash of the cer
40a0: 74 69 66 69 63 61 74 65 20 61 73 20 61 20 68 65 tificate as a he
40b0: 78 20 73 74 72 69 6e 67 2e 0a 54 68 69 73 20 76 x string..This v
40c0: 61 6c 75 65 20 69 73 20 6e 65 77 20 66 6f 72 20 alue is new for
40d0: 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 TclTLS 1.8...[de
40e0: 66 20 22 5b 76 61 72 20 73 68 61 32 35 36 5f 68 f "[var sha256_h
40f0: 61 73 68 5d 20 5b 61 72 67 20 68 61 73 68 5d 22 ash] [arg hash]"
4100: 5d 0a 54 68 65 20 53 48 41 32 35 36 20 68 61 73 ].The SHA256 has
4110: 68 20 6f 66 20 74 68 65 20 63 65 72 74 69 66 69 h of the certifi
4120: 63 61 74 65 20 61 73 20 61 20 68 65 78 20 73 74 cate as a hex st
4130: 72 69 6e 67 2e 0a 54 68 69 73 20 76 61 6c 75 65 ring..This value
4140: 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 is new for TclT
4150: 4c 53 20 31 2e 38 2e 0a 0a 5b 6c 69 73 74 5f 65 LS 1.8...[list_e
4160: 6e 64 5d 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 nd]..[call [cmd
4170: 74 6c 73 3a 3a 63 6f 6e 6e 65 63 74 69 6f 6e 5d tls::connection]
4180: 20 5b 61 72 67 20 63 68 61 6e 6e 65 6c 5d 5d 0a [arg channel]].
4190: 0a 52 65 74 75 72 6e 73 20 74 68 65 20 63 75 72 .Returns the cur
41a0: 72 65 6e 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 rent connection
41b0: 73 74 61 74 75 73 20 6f 66 20 61 6e 20 53 53 4c status of an SSL
41c0: 20 63 68 61 6e 6e 65 6c 2e 20 54 68 65 20 72 65 channel. The re
41d0: 73 75 6c 74 20 69 73 20 61 20 6c 69 73 74 0a 6f sult is a list.o
41e0: 66 20 6b 65 79 2d 76 61 6c 75 65 20 70 61 69 72 f key-value pair
41f0: 73 20 64 65 73 63 72 69 62 69 6e 67 20 74 68 65 s describing the
4200: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 54 68 69 connection..Thi
4210: 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20 6e 65 77 s command is new
4220: 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 2e for TclTLS 1.8.
4230: 20 52 65 74 75 72 6e 65 64 20 76 61 6c 75 65 73 Returned values
4240: 20 69 6e 63 6c 75 64 65 3a 0a 0a 5b 70 61 72 61 include:..[para
4250: 5d 0a 0a 53 53 4c 20 53 74 61 74 75 73 0a 0a 5b ]..SSL Status..[
4260: 6c 69 73 74 5f 62 65 67 69 6e 20 64 65 66 69 6e list_begin defin
4270: 69 74 69 6f 6e 73 5d 0a 0a 5b 64 65 66 20 22 5b itions]..[def "[
4280: 76 61 72 20 73 74 61 74 65 5d 20 5b 61 72 67 20 var state] [arg
4290: 73 74 61 74 65 5d 22 5d 0a 53 74 61 74 65 20 6f state]"].State o
42a0: 66 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e f the connection
42b0: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 65 ...[def "[var se
42c0: 72 76 65 72 6e 61 6d 65 5d 20 5b 61 72 67 20 6e rvername] [arg n
42d0: 61 6d 65 5d 22 5d 0a 54 68 65 20 6e 61 6d 65 20 ame]"].The name
42e0: 6f 66 20 74 68 65 20 63 6f 6e 6e 65 63 74 65 64 of the connected
42f0: 20 74 6f 20 73 65 72 76 65 72 2e 0a 0a 5b 64 65 to server...[de
4300: 66 20 22 5b 76 61 72 20 70 72 6f 74 6f 63 6f 6c f "[var protocol
4310: 5d 20 5b 61 72 67 20 76 65 72 73 69 6f 6e 5d 22 ] [arg version]"
4320: 5d 0a 54 68 65 20 70 72 6f 74 6f 63 6f 6c 20 76 ].The protocol v
4330: 65 72 73 69 6f 6e 20 75 73 65 64 20 66 6f 72 20 ersion used for
4340: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 3a 20 the connection:
4350: 53 53 4c 32 2c 20 53 53 4c 33 2c 20 54 4c 53 31 SSL2, SSL3, TLS1
4360: 2c 20 54 4c 53 31 2e 31 2c 20 54 4c 53 31 2e 32 , TLS1.1, TLS1.2
4370: 2c 20 54 4c 53 31 2e 33 2c 20 6f 72 20 75 6e 6b , TLS1.3, or unk
4380: 6e 6f 77 6e 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 nown...[def "[va
4390: 72 20 72 65 6e 65 67 6f 74 69 61 74 69 6f 6e 5f r renegotiation_
43a0: 61 6c 6c 6f 77 65 64 5d 20 5b 61 72 67 20 62 6f allowed] [arg bo
43b0: 6f 6c 65 61 6e 5d 22 5d 0a 57 68 65 74 68 65 72 olean]"].Whether
43c0: 20 70 72 6f 74 6f 63 6f 6c 20 72 65 6e 65 67 6f protocol renego
43d0: 74 69 61 74 69 6f 6e 20 69 73 20 73 75 70 70 6f tiation is suppo
43e0: 72 74 65 64 20 6f 72 20 6e 6f 74 2e 0a 0a 5b 64 rted or not...[d
43f0: 65 66 20 22 5b 76 61 72 20 73 65 63 75 72 69 74 ef "[var securit
4400: 79 5f 6c 65 76 65 6c 5d 20 5b 61 72 67 20 6c 65 y_level] [arg le
4410: 76 65 6c 5d 22 5d 0a 54 68 65 20 73 65 63 75 72 vel]"].The secur
4420: 69 74 79 20 6c 65 76 65 6c 20 75 73 65 64 20 66 ity level used f
4430: 6f 72 20 73 65 6c 65 63 74 69 6f 6e 20 6f 66 20 or selection of
4440: 63 69 70 68 65 72 73 2c 20 6b 65 79 20 73 69 7a ciphers, key siz
4450: 65 2c 20 65 74 63 2e 0a 0a 5b 64 65 66 20 22 5b e, etc...[def "[
4460: 76 61 72 20 73 65 73 73 69 6f 6e 5f 72 65 75 73 var session_reus
4470: 65 64 5d 20 5b 61 72 67 20 62 6f 6f 6c 65 61 6e ed] [arg boolean
4480: 5d 22 5d 0a 57 68 65 74 68 65 72 20 74 68 65 20 ]"].Whether the
4490: 73 65 73 73 69 6f 6e 20 68 61 73 20 62 65 65 6e session has been
44a0: 20 72 65 75 73 65 64 20 6f 72 20 6e 6f 74 2e 0a reused or not..
44b0: 0a 5b 64 65 66 20 22 5b 76 61 72 20 69 73 5f 73 .[def "[var is_s
44c0: 65 72 76 65 72 5d 20 5b 61 72 67 20 62 6f 6f 6c erver] [arg bool
44d0: 65 61 6e 5d 22 5d 0a 57 68 65 74 68 65 72 20 74 ean]"].Whether t
44e0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 he connection is
44f0: 20 63 6f 6e 66 69 67 75 72 65 64 20 61 73 20 61 configured as a
4500: 20 73 65 72 76 65 72 20 28 31 29 20 6f 72 20 63 server (1) or c
4510: 6c 69 65 6e 74 20 28 30 29 2e 0a 0a 5b 64 65 66 lient (0)...[def
4520: 20 22 5b 76 61 72 20 63 6f 6d 70 72 65 73 73 69 "[var compressi
4530: 6f 6e 5d 20 5b 61 72 67 20 6d 6f 64 65 5d 22 5d on] [arg mode]"]
4540: 0a 43 6f 6d 70 72 65 73 73 69 6f 6e 20 6d 65 74 .Compression met
4550: 68 6f 64 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 hod...[def "[var
4560: 20 65 78 70 61 6e 73 69 6f 6e 5d 20 5b 61 72 67 expansion] [arg
4570: 20 6d 6f 64 65 5d 22 5d 0a 45 78 70 61 6e 73 69 mode]"].Expansi
4580: 6f 6e 20 6d 65 74 68 6f 64 2e 0a 0a 5b 64 65 66 on method...[def
4590: 20 22 5b 76 61 72 20 63 61 4c 69 73 74 5d 20 5b "[var caList] [
45a0: 61 72 67 20 6c 69 73 74 5d 22 5d 0a 4c 69 73 74 arg list]"].List
45b0: 20 6f 66 20 43 65 72 74 69 66 69 63 61 74 65 20 of Certificate
45c0: 41 75 74 68 6f 72 69 74 69 65 73 20 28 43 41 29 Authorities (CA)
45d0: 20 66 6f 72 20 58 2e 35 30 39 20 63 65 72 74 69 for X.509 certi
45e0: 66 69 63 61 74 65 2e 0a 0a 5b 6c 69 73 74 5f 65 ficate...[list_e
45f0: 6e 64 5d 0a 0a 43 69 70 68 65 72 20 49 6e 66 6f nd]..Cipher Info
4600: 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e 20 64 65 ..[list_begin de
4610: 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a 5b 64 65 66 finitions]..[def
4620: 20 22 5b 76 61 72 20 63 69 70 68 65 72 5d 20 5b "[var cipher] [
4630: 61 72 67 20 63 69 70 68 65 72 5d 22 5d 0a 54 68 arg cipher]"].Th
4640: 65 20 63 75 72 72 65 6e 74 20 63 69 70 68 65 72 e current cipher
4650: 20 69 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 in use for the
4660: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 0a 5b 64 65 connection...[de
4670: 66 20 22 5b 76 61 72 20 73 74 61 6e 64 61 72 64 f "[var standard
4680: 5f 6e 61 6d 65 5d 20 5b 61 72 67 20 6e 61 6d 65 _name] [arg name
4690: 5d 22 5d 0a 54 68 65 20 73 74 61 6e 64 61 72 64 ]"].The standard
46a0: 20 52 46 43 20 6e 61 6d 65 20 6f 66 20 63 69 70 RFC name of cip
46b0: 68 65 72 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 her...[def "[var
46c0: 20 61 6c 67 6f 72 69 74 68 6d 5f 62 69 74 73 5d algorithm_bits]
46d0: 20 5b 61 72 67 20 6e 5d 22 5d 0a 54 68 65 20 6e [arg n]"].The n
46e0: 75 6d 62 65 72 20 6f 66 20 70 72 6f 63 65 73 73 umber of process
46f0: 65 64 20 62 69 74 73 20 75 73 65 64 20 66 6f 72 ed bits used for
4700: 20 63 69 70 68 65 72 2e 0a 0a 5b 64 65 66 20 22 cipher...[def "
4710: 5b 76 61 72 20 73 65 63 72 65 74 5f 62 69 74 73 [var secret_bits
4720: 5d 20 5b 61 72 67 20 6e 5d 22 5d 0a 54 68 65 20 ] [arg n]"].The
4730: 6e 75 6d 62 65 72 20 6f 66 20 73 65 63 72 65 74 number of secret
4740: 20 62 69 74 73 20 75 73 65 64 20 66 6f 72 20 63 bits used for c
4750: 69 70 68 65 72 2e 0a 0a 5b 64 65 66 20 22 5b 76 ipher...[def "[v
4760: 61 72 20 6d 69 6e 5f 76 65 72 73 69 6f 6e 5d 20 ar min_version]
4770: 5b 61 72 67 20 76 65 72 73 69 6f 6e 5d 22 5d 0a [arg version]"].
4780: 54 68 65 20 6d 69 6e 69 6d 75 6d 20 70 72 6f 74 The minimum prot
4790: 6f 63 6f 6c 20 76 65 72 73 69 6f 6e 20 66 6f 72 ocol version for
47a0: 20 63 69 70 68 65 72 2e 0a 0a 5b 64 65 66 20 22 cipher...[def "
47b0: 5b 76 61 72 20 63 69 70 68 65 72 5f 69 73 5f 61 [var cipher_is_a
47c0: 65 61 64 5d 20 5b 61 72 67 20 62 6f 6f 6c 65 61 ead] [arg boolea
47d0: 6e 5d 22 5d 0a 57 68 65 74 68 65 72 20 74 68 65 n]"].Whether the
47e0: 20 63 69 70 68 65 72 20 69 73 20 41 75 74 68 65 cipher is Authe
47f0: 6e 74 69 63 61 74 65 64 20 45 6e 63 72 79 70 74 nticated Encrypt
4800: 69 6f 6e 20 77 69 74 68 20 41 73 73 6f 63 69 61 ion with Associa
4810: 74 65 64 20 44 61 74 61 20 28 41 45 41 44 29 2e ted Data (AEAD).
4820: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 63 69 70 ..[def "[var cip
4830: 68 65 72 5f 69 64 5d 20 5b 61 72 67 20 69 64 5d her_id] [arg id]
4840: 22 5d 0a 54 68 65 20 4f 70 65 6e 53 53 4c 20 63 "].The OpenSSL c
4850: 69 70 68 65 72 20 69 64 2e 0a 0a 5b 64 65 66 20 ipher id...[def
4860: 22 5b 76 61 72 20 64 65 73 63 72 69 70 74 69 6f "[var descriptio
4870: 6e 5d 20 5b 61 72 67 20 73 74 72 69 6e 67 5d 22 n] [arg string]"
4880: 5d 0a 41 20 74 65 78 74 20 64 65 73 63 72 69 70 ].A text descrip
4890: 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 69 70 68 tion of the ciph
48a0: 65 72 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 er...[def "[var
48b0: 68 61 6e 64 73 68 61 6b 65 5f 64 69 67 65 73 74 handshake_digest
48c0: 5d 20 5b 61 72 67 20 62 6f 6f 6c 65 61 6e 5d 22 ] [arg boolean]"
48d0: 5d 0a 44 69 67 65 73 74 20 75 73 65 64 20 64 75 ].Digest used du
48e0: 72 69 6e 67 20 68 61 6e 64 73 68 61 6b 65 2e 0a ring handshake..
48f0: 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 53 65 73 .[list_end]..Ses
4900: 73 69 6f 6e 20 49 6e 66 6f 0a 0a 5b 6c 69 73 74 sion Info..[list
4910: 5f 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 6f _begin definitio
4920: 6e 73 5d 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 ns]..[def "[var
4930: 61 6c 70 6e 5d 20 5b 61 72 67 20 70 72 6f 74 6f alpn] [arg proto
4940: 63 6f 6c 5d 22 5d 0a 54 68 65 20 70 72 6f 74 6f col]"].The proto
4950: 63 6f 6c 20 73 65 6c 65 63 74 65 64 20 61 66 74 col selected aft
4960: 65 72 20 41 70 70 6c 69 63 61 74 69 6f 6e 2d 4c er Application-L
4970: 61 79 65 72 20 50 72 6f 74 6f 63 6f 6c 20 4e 65 ayer Protocol Ne
4980: 67 6f 74 69 61 74 69 6f 6e 20 28 41 4c 50 4e 29 gotiation (ALPN)
4990: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 72 65 ...[def "[var re
49a0: 73 75 6d 61 62 6c 65 5d 20 5b 61 72 67 20 62 6f sumable] [arg bo
49b0: 6f 6c 65 61 6e 5d 22 5d 0a 57 68 65 74 68 65 72 olean]"].Whether
49c0: 20 74 68 65 20 73 65 73 73 69 6f 6e 20 63 61 6e the session can
49d0: 20 62 65 20 72 65 73 75 6d 65 64 20 6f 72 20 6e be resumed or n
49e0: 6f 74 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 ot...[def "[var
49f0: 73 74 61 72 74 5f 74 69 6d 65 5d 20 5b 61 72 67 start_time] [arg
4a00: 20 73 65 63 6f 6e 64 73 5d 22 5d 0a 54 69 6d 65 seconds]"].Time
4a10: 20 73 69 6e 63 65 20 73 65 73 73 69 6f 6e 20 73 since session s
4a20: 74 61 72 74 65 64 20 69 6e 20 73 65 63 6f 6e 64 tarted in second
4a30: 73 20 73 69 6e 63 65 20 65 70 6f 63 68 2e 0a 0a s since epoch...
4a40: 5b 64 65 66 20 22 5b 76 61 72 20 74 69 6d 65 6f [def "[var timeo
4a50: 75 74 5d 20 5b 61 72 67 20 73 65 63 6f 6e 64 73 ut] [arg seconds
4a60: 5d 22 5d 0a 4d 61 78 20 64 75 72 61 74 69 6f 6e ]"].Max duration
4a70: 20 6f 66 20 73 65 73 73 69 6f 6e 20 69 6e 20 73 of session in s
4a80: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 69 econds before ti
4a90: 6d 65 2d 6f 75 74 2e 0a 0a 5b 64 65 66 20 22 5b me-out...[def "[
4aa0: 76 61 72 20 6c 69 66 65 74 69 6d 65 5d 20 5b 61 var lifetime] [a
4ab0: 72 67 20 73 65 63 6f 6e 64 73 5d 22 5d 0a 53 65 rg seconds]"].Se
4ac0: 73 73 69 6f 6e 20 74 69 63 6b 65 74 20 6c 69 66 ssion ticket lif
4ad0: 65 74 69 6d 65 20 68 69 6e 74 20 69 6e 20 73 65 etime hint in se
4ae0: 63 6f 6e 64 73 2e 0a 0a 5b 64 65 66 20 22 5b 76 conds...[def "[v
4af0: 61 72 20 73 65 73 73 69 6f 6e 5f 69 64 5d 20 5b ar session_id] [
4b00: 61 72 67 20 62 69 6e 61 72 79 5f 73 74 72 69 6e arg binary_strin
4b10: 67 5d 22 5d 0a 55 6e 69 71 75 65 20 73 65 73 73 g]"].Unique sess
4b20: 69 6f 6e 20 69 64 20 66 6f 72 20 75 73 65 20 69 ion id for use i
4b30: 6e 20 72 65 73 75 6d 69 6e 67 20 74 68 65 20 73 n resuming the s
4b40: 65 73 73 69 6f 6e 2e 0a 0a 5b 64 65 66 20 22 5b ession...[def "[
4b50: 76 61 72 20 73 65 73 73 69 6f 6e 5f 74 69 63 6b var session_tick
4b60: 65 74 5d 20 5b 61 72 67 20 62 69 6e 61 72 79 5f et] [arg binary_
4b70: 73 74 72 69 6e 67 5d 22 5d 0a 55 6e 69 71 75 65 string]"].Unique
4b80: 20 73 65 73 73 69 6f 6e 20 74 69 63 6b 65 74 20 session ticket
4b90: 66 6f 72 20 75 73 65 20 69 6e 20 72 65 73 75 6d for use in resum
4ba0: 69 6e 67 20 74 68 65 20 73 65 73 73 69 6f 6e 2e ing the session.
4bb0: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 74 69 63 ..[def "[var tic
4bc0: 6b 65 74 5f 61 70 70 5f 64 61 74 61 5d 20 5b 61 ket_app_data] [a
4bd0: 72 67 20 62 69 6e 61 72 79 5f 73 74 72 69 6e 67 rg binary_string
4be0: 5d 22 5d 0a 55 6e 69 71 75 65 20 73 65 73 73 69 ]"].Unique sessi
4bf0: 6f 6e 20 74 69 63 6b 65 74 20 61 70 70 6c 69 63 on ticket applic
4c00: 61 74 69 6f 6e 20 64 61 74 61 2e 0a 0a 5b 64 65 ation data...[de
4c10: 66 20 22 5b 76 61 72 20 6d 61 73 74 65 72 5f 6b f "[var master_k
4c20: 65 79 5d 20 5b 61 72 67 20 62 69 6e 61 72 79 5f ey] [arg binary_
4c30: 73 74 72 69 6e 67 5d 22 5d 0a 55 6e 69 71 75 65 string]"].Unique
4c40: 20 73 65 73 73 69 6f 6e 20 6d 61 73 74 65 72 20 session master
4c50: 6b 65 79 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 key...[def "[var
4c60: 20 73 65 73 73 69 6f 6e 5f 63 61 63 68 65 5f 6d session_cache_m
4c70: 6f 64 65 5d 20 5b 61 72 67 20 6d 6f 64 65 5d 22 ode] [arg mode]"
4c80: 5d 0a 53 65 72 76 65 72 20 63 61 63 68 65 20 6d ].Server cache m
4c90: 6f 64 65 20 28 63 6c 69 65 6e 74 2c 20 73 65 72 ode (client, ser
4ca0: 76 65 72 2c 20 6f 72 20 62 6f 74 68 29 2e 0a 0a ver, or both)...
4cb0: 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 63 61 6c [list_end]..[cal
4cc0: 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a 63 69 70 68 l [cmd tls::ciph
4cd0: 65 72 73 5d 20 5b 6f 70 74 20 5b 61 72 67 20 70 ers] [opt [arg p
4ce0: 72 6f 74 6f 63 6f 6c 5d 5d 20 5b 6f 70 74 20 5b rotocol]] [opt [
4cf0: 61 72 67 20 76 65 72 62 6f 73 65 5d 5d 20 5b 6f arg verbose]] [o
4d00: 70 74 20 5b 61 72 67 20 73 75 70 70 6f 72 74 65 pt [arg supporte
4d10: 64 5d 5d 5d 0a 0a 57 69 74 68 6f 75 74 20 61 6e d]]]..Without an
4d20: 79 20 6f 70 74 69 6f 6e 73 2c 20 69 74 20 72 65 y options, it re
4d30: 74 75 72 6e 73 20 61 20 6c 69 73 74 20 6f 66 20 turns a list of
4d40: 61 6c 6c 20 73 79 6d 6d 65 74 72 69 63 20 63 69 all symmetric ci
4d50: 70 68 65 72 73 20 66 6f 72 20 75 73 65 20 77 69 phers for use wi
4d60: 74 68 20 74 68 65 0a 5b 61 72 67 20 2d 63 69 70 th the.[arg -cip
4d70: 68 65 72 5d 20 6f 70 74 69 6f 6e 2e 20 57 69 74 her] option. Wit
4d80: 68 20 5b 61 72 67 20 70 72 6f 74 6f 63 6f 6c 5d h [arg protocol]
4d90: 2c 20 6f 6e 6c 79 20 74 68 65 20 63 69 70 68 65 , only the ciphe
4da0: 72 73 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 rs supported for
4db0: 20 74 68 61 74 0a 70 72 6f 74 6f 63 6f 6c 20 61 that.protocol a
4dc0: 72 65 20 72 65 74 75 72 6e 65 64 2e 20 53 65 65 re returned. See
4dd0: 20 74 68 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 the [cmd tls::p
4de0: 72 6f 74 6f 63 6f 6c 73 5d 20 63 6f 6d 6d 61 6e rotocols] comman
4df0: 64 20 66 6f 72 20 74 68 65 20 73 75 70 70 6f 72 d for the suppor
4e00: 74 65 64 0a 70 72 6f 74 6f 63 6f 6c 73 2e 20 49 ted.protocols. I
4e10: 66 20 5b 61 72 67 20 76 65 72 62 6f 73 65 5d 20 f [arg verbose]
4e20: 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 is specified as
4e30: 74 72 75 65 20 74 68 65 6e 20 61 20 76 65 72 62 true then a verb
4e40: 6f 73 65 2c 20 68 75 6d 61 6e 20 72 65 61 64 61 ose, human reada
4e50: 62 6c 65 0a 6c 69 73 74 20 69 73 20 72 65 74 75 ble.list is retu
4e60: 72 6e 65 64 20 77 69 74 68 20 61 64 64 69 74 69 rned with additi
4e70: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
4e80: 20 6f 6e 20 74 68 65 20 63 69 70 68 65 72 2e 20 on the cipher.
4e90: 49 66 20 5b 61 72 67 20 73 75 70 70 6f 72 74 65 If [arg supporte
4ea0: 64 5d 0a 69 73 20 73 70 65 63 69 66 69 65 64 20 d].is specified
4eb0: 61 73 20 74 72 75 65 2c 20 74 68 65 6e 20 6f 6e as true, then on
4ec0: 6c 79 20 74 68 65 20 63 69 70 68 65 72 73 20 73 ly the ciphers s
4ed0: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 70 72 6f upported for pro
4ee0: 74 6f 63 6f 6c 20 77 69 6c 6c 20 62 65 20 6c 69 tocol will be li
4ef0: 73 74 65 64 2e 0a 54 68 65 20 5b 61 72 67 20 73 sted..The [arg s
4f00: 75 70 70 6f 72 74 65 64 5d 20 61 72 67 20 69 73 upported] arg is
4f10: 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 new for TclTLS
4f20: 31 2e 38 2e 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 1.8...[call [cmd
4f30: 20 74 6c 73 3a 3a 70 72 6f 74 6f 63 6f 6c 73 5d tls::protocols]
4f40: 5d 0a 0a 52 65 74 75 72 6e 73 20 61 20 6c 69 73 ]..Returns a lis
4f50: 74 20 6f 66 20 74 68 65 20 73 75 70 70 6f 72 74 t of the support
4f60: 65 64 20 53 53 4c 2f 54 4c 53 20 70 72 6f 74 6f ed SSL/TLS proto
4f70: 63 6f 6c 73 2e 20 56 61 6c 69 64 20 76 61 6c 75 cols. Valid valu
4f80: 65 73 20 61 72 65 3a 0a 5b 63 6f 6e 73 74 20 73 es are:.[const s
4f90: 73 6c 32 5d 2c 20 5b 63 6f 6e 73 74 20 73 73 6c sl2], [const ssl
4fa0: 33 5d 2c 20 5b 63 6f 6e 73 74 20 74 6c 73 31 5d 3], [const tls1]
4fb0: 2c 20 5b 63 6f 6e 73 74 20 74 6c 73 31 2e 31 5d , [const tls1.1]
4fc0: 2c 20 5b 63 6f 6e 73 74 20 74 6c 73 31 2e 32 5d , [const tls1.2]
4fd0: 2c 20 61 6e 64 0a 5b 63 6f 6e 73 74 20 74 6c 73 , and.[const tls
4fe0: 31 2e 33 5d 2e 20 45 78 61 63 74 20 6c 69 73 74 1.3]. Exact list
4ff0: 20 64 65 70 65 6e 64 73 20 6f 6e 20 4f 70 65 6e depends on Open
5000: 53 53 4c 20 76 65 72 73 69 6f 6e 20 61 6e 64 20 SSL version and
5010: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 66 6c 61 compile time fla
5020: 67 73 2e 0a 54 68 69 73 20 63 6f 6d 6d 61 6e 64 gs..This command
5030: 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 is new for TclT
5040: 4c 53 20 31 2e 38 2e 0a 0a 5b 63 61 6c 6c 20 5b LS 1.8...[call [
5050: 63 6d 64 20 74 6c 73 3a 3a 76 65 72 73 69 6f 6e cmd tls::version
5060: 5d 5d 0a 0a 52 65 74 75 72 6e 73 20 74 68 65 20 ]]..Returns the
5070: 4f 70 65 6e 53 53 4c 20 76 65 72 73 69 6f 6e 20 OpenSSL version
5080: 73 74 72 69 6e 67 2e 0a 0a 5b 6c 69 73 74 5f 65 string...[list_e
5090: 6e 64 5d 0a 0a 0a 5b 73 65 63 74 69 6f 6e 20 22 nd]...[section "
50a0: 43 65 72 74 69 66 69 63 61 74 65 20 56 61 6c 69 Certificate Vali
50b0: 64 61 74 69 6f 6e 22 5d 0a 0a 5b 73 75 62 73 65 dation"]..[subse
50c0: 63 74 69 6f 6e 20 22 50 4b 49 20 61 6e 64 20 43 ction "PKI and C
50d0: 65 72 74 69 66 69 63 61 74 65 73 22 5d 0a 0a 55 ertificates"]..U
50e0: 73 69 6e 67 20 74 68 65 20 50 75 62 6c 69 63 20 sing the Public
50f0: 4b 65 79 20 49 6e 66 72 61 73 74 72 75 63 74 75 Key Infrastructu
5100: 72 65 20 28 50 4b 49 29 2c 20 65 61 63 68 20 75 re (PKI), each u
5110: 73 65 72 20 63 72 65 61 74 65 73 20 61 20 70 72 ser creates a pr
5120: 69 76 61 74 65 20 6b 65 79 20 74 68 61 74 0a 6f ivate key that.o
5130: 6e 6c 79 20 74 68 65 79 20 6b 6e 6f 77 20 61 62 nly they know ab
5140: 6f 75 74 20 61 6e 64 20 61 20 70 75 62 6c 69 63 out and a public
5150: 20 6b 65 79 20 74 68 65 79 20 63 61 6e 20 65 78 key they can ex
5160: 63 68 61 6e 67 65 20 77 69 74 68 20 6f 74 68 65 change with othe
5170: 72 73 20 66 6f 72 20 75 73 65 20 69 6e 0a 65 6e rs for use in.en
5180: 63 72 79 70 74 69 6e 67 20 61 6e 64 20 64 65 63 crypting and dec
5190: 72 79 70 74 69 6e 67 20 64 61 74 61 2e 20 54 68 rypting data. Th
51a0: 65 20 70 72 6f 63 65 73 73 20 69 73 20 74 68 65 e process is the
51b0: 20 73 65 6e 64 65 72 20 65 6e 63 72 79 70 74 73 sender encrypts
51c0: 20 74 68 65 69 72 20 64 61 74 61 0a 75 73 69 6e their data.usin
51d0: 67 20 74 68 65 69 72 20 70 72 69 76 61 74 65 20 g their private
51e0: 6b 65 79 20 61 6e 64 20 74 68 65 20 72 65 63 65 key and the rece
51f0: 69 76 65 72 27 73 20 70 75 62 6c 69 63 20 6b 65 iver's public ke
5200: 79 2e 20 54 68 65 20 64 61 74 61 20 69 73 20 74 y. The data is t
5210: 68 65 6e 20 73 65 6e 74 0a 74 6f 20 74 68 65 20 hen sent.to the
5220: 72 65 63 65 69 76 65 72 2e 20 49 6e 20 61 20 73 receiver. In a s
5230: 69 6d 69 6c 61 72 20 6d 61 6e 6e 65 72 2c 20 74 imilar manner, t
5240: 68 65 20 72 65 63 65 69 76 65 72 20 75 73 65 73 he receiver uses
5250: 20 74 68 65 69 72 20 70 72 69 76 61 74 65 20 6b their private k
5260: 65 79 20 61 6e 64 0a 74 68 65 20 73 65 6e 64 65 ey and.the sende
5270: 72 27 73 20 70 75 62 6c 69 63 20 6b 65 79 20 74 r's public key t
5280: 6f 20 64 65 63 72 79 70 74 20 74 68 65 20 64 61 o decrypt the da
5290: 74 61 2e 20 54 68 69 73 20 70 72 6f 76 69 64 65 ta. This provide
52a0: 73 20 64 61 74 61 20 69 6e 74 65 67 72 69 74 79 s data integrity
52b0: 2c 20 74 6f 0a 65 6e 73 75 72 65 20 74 68 65 20 , to.ensure the
52c0: 64 61 74 61 20 63 61 6e 27 74 20 62 65 20 76 69 data can't be vi
52d0: 65 77 65 64 20 6f 72 20 61 6c 74 65 72 65 64 20 ewed or altered
52e0: 64 75 72 69 6e 67 20 74 72 61 6e 73 70 6f 72 74 during transport
52f0: 2e 20 53 65 65 20 74 68 65 0a 5b 6f 70 74 69 6f . See the.[optio
5300: 6e 20 2d 6b 65 79 5d 20 61 6e 64 20 5b 6f 70 74 n -key] and [opt
5310: 69 6f 6e 20 2d 6b 65 79 66 69 6c 65 5d 20 6f 70 ion -keyfile] op
5320: 74 69 6f 6e 73 20 66 6f 72 20 68 6f 77 20 74 6f tions for how to
5330: 20 73 70 65 63 69 66 79 20 74 68 65 20 70 72 69 specify the pri
5340: 76 61 74 65 20 6b 65 79 2e 0a 41 6c 73 6f 20 73 vate key..Also s
5350: 65 65 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d ee the [option -
5360: 70 61 73 73 77 6f 72 64 5d 20 6f 70 74 69 6f 6e password] option
5370: 20 66 6f 72 20 68 6f 77 20 74 6f 20 70 72 6f 76 for how to prov
5380: 69 64 65 20 74 68 65 20 70 61 73 73 77 6f 72 64 ide the password
5390: 2e 0a 5b 70 61 72 61 5d 0a 49 6e 20 6f 72 64 65 ..[para].In orde
53a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 75 74 r to provide aut
53b0: 68 65 6e 74 69 63 61 74 69 6f 6e 2c 20 69 2e 65 hentication, i.e
53c0: 2e 20 65 6e 73 75 72 69 6e 67 20 73 6f 6d 65 6f . ensuring someo
53d0: 6e 65 20 69 73 20 77 68 6f 20 74 68 65 79 20 73 ne is who they s
53e0: 61 79 20 74 68 65 79 0a 61 72 65 2c 20 74 68 65 ay they.are, the
53f0: 20 70 75 62 6c 69 63 20 6b 65 79 20 61 6e 64 20 public key and
5400: 75 73 65 72 20 69 64 65 6e 74 69 66 69 63 61 74 user identificat
5410: 69 6f 6e 20 69 6e 66 6f 20 69 73 20 73 74 6f 72 ion info is stor
5420: 65 64 20 69 6e 20 61 20 58 2e 35 30 39 0a 63 65 ed in a X.509.ce
5430: 72 74 69 66 69 63 61 74 65 20 61 6e 64 20 74 68 rtificate and th
5440: 61 74 20 63 65 72 74 69 66 69 63 61 74 65 20 69 at certificate i
5450: 73 20 61 75 74 68 65 6e 74 69 63 61 74 65 64 20 s authenticated
5460: 28 69 2e 65 2e 20 73 69 67 6e 65 64 29 20 62 79 (i.e. signed) by
5470: 20 61 20 43 65 72 74 69 66 69 63 61 74 65 0a 41 a Certificate.A
5480: 75 74 68 6f 72 69 74 79 20 28 43 41 29 2e 20 55 uthority (CA). U
5490: 73 65 72 73 20 63 61 6e 20 74 68 65 6e 20 65 78 sers can then ex
54a0: 63 68 61 6e 67 65 20 74 68 65 73 65 20 63 65 72 change these cer
54b0: 74 69 66 69 63 61 74 65 73 20 64 75 72 69 6e 67 tificates during
54c0: 20 74 68 65 20 54 4c 53 0a 69 6e 69 74 69 61 6c the TLS.initial
54d0: 69 7a 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 20 ization process
54e0: 61 6e 64 20 63 68 65 63 6b 20 74 68 65 6d 20 61 and check them a
54f0: 67 61 69 6e 73 74 20 74 68 65 20 72 6f 6f 74 20 gainst the root
5500: 43 41 20 63 65 72 74 69 66 69 63 61 74 65 73 20 CA certificates
5510: 74 6f 20 65 6e 73 75 72 65 0a 74 68 65 79 20 61 to ensure.they a
5520: 72 65 20 76 61 6c 69 64 2e 20 54 68 69 73 20 69 re valid. This i
5530: 73 20 68 61 6e 64 6c 65 64 20 62 79 20 4f 70 65 s handled by Ope
5540: 6e 53 53 4c 20 76 69 61 20 74 68 65 20 5b 6f 70 nSSL via the [op
5550: 74 69 6f 6e 20 2d 72 65 71 75 65 73 74 5d 20 61 tion -request] a
5560: 6e 64 0a 5b 6f 70 74 69 6f 6e 20 2d 72 65 71 75 nd.[option -requ
5570: 69 72 65 5d 20 6f 70 74 69 6f 6e 73 2e 20 53 65 ire] options. Se
5580: 65 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 63 e the [option -c
5590: 61 64 69 72 5d 2c 20 5b 6f 70 74 69 6f 6e 20 2d adir], [option -
55a0: 63 61 64 69 72 5d 2c 20 61 6e 64 0a 5b 6f 70 74 cadir], and.[opt
55b0: 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f 70 ion -castore] op
55c0: 74 69 6f 6e 73 20 66 6f 72 20 68 6f 77 20 74 6f tions for how to
55d0: 20 73 70 65 63 69 66 79 20 77 68 65 72 65 20 74 specify where t
55e0: 6f 20 66 69 6e 64 20 74 68 65 20 43 41 20 63 65 o find the CA ce
55f0: 72 74 69 66 69 63 61 74 65 73 2e 0a 4f 70 74 69 rtificates..Opti
5600: 6f 6e 61 6c 6c 79 2c 20 69 6e 20 61 20 66 75 74 onally, in a fut
5610: 75 72 65 20 72 65 6c 65 61 73 65 2c 20 74 68 65 ure release, the
5620: 79 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 63 68 y can also be ch
5630: 65 63 6b 65 64 20 61 67 61 69 6e 73 74 20 74 68 ecked against th
5640: 65 20 43 65 72 74 69 66 69 63 61 74 65 0a 52 65 e Certificate.Re
5650: 76 6f 63 61 74 69 6f 6e 20 4c 69 73 74 20 28 43 vocation List (C
5660: 52 4c 29 20 6f 66 20 72 65 76 6f 6b 65 64 20 63 RL) of revoked c
5670: 65 72 74 69 66 69 63 61 74 65 73 2e 20 43 65 72 ertificates. Cer
5680: 74 69 66 69 63 61 74 65 73 20 63 61 6e 20 61 6c tificates can al
5690: 73 6f 20 62 65 0a 73 65 6c 66 2d 73 69 67 6e 65 so be.self-signe
56a0: 64 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 20 d, but they are
56b0: 62 79 20 64 65 66 61 75 6c 74 20 6e 6f 74 20 74 by default not t
56c0: 72 75 73 74 65 64 20 75 6e 6c 65 73 73 20 79 6f rusted unless yo
56d0: 75 20 61 64 64 20 74 68 65 6d 20 74 6f 20 79 6f u add them to yo
56e0: 75 72 0a 63 65 72 74 69 66 69 63 61 74 65 20 73 ur.certificate s
56f0: 74 6f 72 65 2e 0a 5b 70 61 72 61 5d 0a 54 79 70 tore..[para].Typ
5700: 69 63 61 6c 6c 79 20 77 68 65 6e 20 76 69 73 69 ically when visi
5710: 74 69 6e 67 20 77 65 62 20 73 69 74 65 73 2c 20 ting web sites,
5720: 6f 6e 6c 79 20 74 68 65 20 63 6c 69 65 6e 74 20 only the client
5730: 6e 65 65 64 73 20 74 6f 20 63 68 65 63 6b 20 74 needs to check t
5740: 68 65 20 73 65 72 76 65 72 27 73 0a 63 65 72 74 he server's.cert
5750: 69 66 69 63 61 74 65 20 74 6f 20 65 6e 73 75 72 ificate to ensur
5760: 65 20 69 74 20 69 73 20 76 61 6c 69 64 2e 20 54 e it is valid. T
5770: 68 65 20 73 65 72 76 65 72 20 64 6f 65 73 6e 27 he server doesn'
5780: 74 20 6e 65 65 64 20 74 6f 20 63 68 65 63 6b 20 t need to check
5790: 74 68 65 20 63 6c 69 65 6e 74 0a 63 65 72 74 69 the client.certi
57a0: 66 69 63 61 74 65 20 75 6e 6c 65 73 73 20 79 6f ficate unless yo
57b0: 75 20 6e 65 65 64 20 74 6f 20 61 75 74 68 65 6e u need to authen
57c0: 74 69 63 61 74 65 20 77 69 74 68 20 74 68 65 6d ticate with them
57d0: 20 74 6f 20 6c 6f 67 69 6e 2c 20 65 74 63 2e 20 to login, etc.
57e0: 53 65 65 20 74 68 65 0a 5b 6f 70 74 69 6f 6e 20 See the.[option
57f0: 2d 63 65 72 74 5d 20 61 6e 64 20 5b 6f 70 74 69 -cert] and [opti
5800: 6f 6e 20 2d 63 65 72 74 66 69 6c 65 5d 20 6f 70 on -certfile] op
5810: 74 69 6f 6e 73 20 69 66 20 79 6f 75 20 6e 65 65 tions if you nee
5820: 64 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 d to provide a c
5830: 65 72 74 69 66 69 63 61 74 65 2e 0a 0a 0a 5b 73 ertificate....[s
5840: 75 62 73 65 63 74 69 6f 6e 20 22 53 75 6d 6d 61 ubsection "Summa
5850: 72 79 20 6f 66 20 63 6f 6d 6d 61 6e 64 20 6c 69 ry of command li
5860: 6e 65 20 6f 70 74 69 6f 6e 73 22 5d 0a 0a 54 68 ne options"]..Th
5870: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 74 69 e following opti
5880: 6f 6e 73 20 61 72 65 20 75 73 65 64 20 66 6f 72 ons are used for
5890: 20 70 65 65 72 20 63 65 72 74 69 66 69 63 61 74 peer certificat
58a0: 65 20 76 61 6c 69 64 61 74 69 6f 6e 3a 0a 0a 5b e validation:..[
58b0: 6c 69 73 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f list_begin optio
58c0: 6e 73 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 ns]..[opt_def -c
58d0: 61 64 69 72 20 5b 61 72 67 20 64 69 72 65 63 74 adir [arg direct
58e0: 6f 72 79 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 ory]].Specifies
58f0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 77 68 the directory wh
5900: 65 72 65 20 74 68 65 20 43 65 72 74 69 66 69 63 ere the Certific
5910: 61 74 65 20 41 75 74 68 6f 72 69 74 79 20 28 43 ate Authority (C
5920: 41 29 20 63 65 72 74 69 66 69 63 61 74 65 73 20 A) certificates
5930: 61 72 65 0a 73 74 6f 72 65 64 2e 20 54 68 65 20 are.stored. The
5940: 64 65 66 61 75 6c 74 20 69 73 20 70 6c 61 74 66 default is platf
5950: 6f 72 6d 20 73 70 65 63 69 66 69 63 2c 20 62 75 orm specific, bu
5960: 74 20 69 73 20 75 73 75 61 6c 6c 79 20 5b 66 69 t is usually [fi
5970: 6c 65 20 2f 65 74 63 2f 73 73 6c 2f 63 65 72 74 le /etc/ssl/cert
5980: 73 5d 20 6f 6e 0a 4c 69 6e 75 78 2f 55 6e 69 78 s] on.Linux/Unix
5990: 20 73 79 73 74 65 6d 73 2e 20 54 68 65 20 64 65 systems. The de
59a0: 66 61 75 6c 74 20 6c 6f 63 61 74 69 6f 6e 20 63 fault location c
59b0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
59c0: 20 62 79 20 74 68 65 0a 5b 76 61 72 20 53 53 4c by the.[var SSL
59d0: 5f 43 45 52 54 5f 44 49 52 5d 20 65 6e 76 69 72 _CERT_DIR] envir
59e0: 6f 6e 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 2e onment variable.
59f0: 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 61 66 69 ..[opt_def -cafi
5a00: 6c 65 20 5b 61 72 67 20 66 69 6c 65 6e 61 6d 65 le [arg filename
5a10: 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 ]].Specifies the
5a20: 20 66 69 6c 65 20 77 69 74 68 20 74 68 65 20 43 file with the C
5a30: 65 72 74 69 66 69 63 61 74 65 20 41 75 74 68 6f ertificate Autho
5a40: 72 69 74 79 20 28 43 41 29 20 63 65 72 74 69 66 rity (CA) certif
5a50: 69 63 61 74 65 73 20 74 6f 20 75 73 65 20 69 6e icates to use in
5a60: 0a 5b 63 6f 6e 73 74 20 50 45 4d 5d 20 66 69 6c .[const PEM] fil
5a70: 65 20 66 6f 72 6d 61 74 2e 20 54 68 65 20 64 65 e format. The de
5a80: 66 61 75 6c 74 20 69 73 20 5b 66 69 6c 65 20 63 fault is [file c
5a90: 65 72 74 2e 70 65 6d 5d 2c 20 69 6e 20 74 68 65 ert.pem], in the
5aa0: 20 4f 70 65 6e 53 53 4c 0a 64 69 72 65 63 74 6f OpenSSL.directo
5ab0: 72 79 2e 20 4f 6e 20 4c 69 6e 75 78 2f 55 6e 69 ry. On Linux/Uni
5ac0: 78 20 73 79 73 74 65 6d 73 2c 20 74 68 69 73 20 x systems, this
5ad0: 69 73 20 75 73 75 61 6c 6c 79 20 5b 66 69 6c 65 is usually [file
5ae0: 20 2f 65 74 63 2f 73 73 6c 2f 63 61 2d 62 75 6e /etc/ssl/ca-bun
5af0: 64 6c 65 2e 70 65 6d 5d 2e 0a 54 68 65 20 64 65 dle.pem]..The de
5b00: 66 61 75 6c 74 20 66 69 6c 65 20 63 61 6e 20 62 fault file can b
5b10: 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
5b20: 74 68 65 20 5b 76 61 72 20 53 53 4c 5f 43 45 52 the [var SSL_CER
5b30: 54 5f 46 49 4c 45 5d 20 65 6e 76 69 72 6f 6e 6d T_FILE] environm
5b40: 65 6e 74 0a 76 61 72 69 61 62 6c 65 2e 0a 0a 5b ent.variable...[
5b50: 6f 70 74 5f 64 65 66 20 2d 63 61 73 74 6f 72 65 opt_def -castore
5b60: 20 5b 61 72 67 20 55 52 49 5d 5d 0a 53 70 65 63 [arg URI]].Spec
5b70: 69 66 69 65 73 20 74 68 65 20 55 6e 69 66 6f 72 ifies the Unifor
5b80: 6d 20 52 65 73 6f 75 72 63 65 20 49 64 65 6e 74 m Resource Ident
5b90: 69 66 69 65 72 20 28 55 52 49 29 20 66 6f 72 20 ifier (URI) for
5ba0: 74 68 65 20 43 65 72 74 69 66 69 63 61 74 65 20 the Certificate
5bb0: 41 75 74 68 6f 72 69 74 79 0a 28 43 41 29 20 73 Authority.(CA) s
5bc0: 74 6f 72 65 2c 20 77 68 69 63 68 20 6d 61 79 20 tore, which may
5bd0: 62 65 20 61 20 73 69 6e 67 6c 65 20 63 6f 6e 74 be a single cont
5be0: 61 69 6e 65 72 20 6f 72 20 61 20 63 61 74 61 6c ainer or a catal
5bf0: 6f 67 20 6f 66 20 63 6f 6e 74 61 69 6e 65 72 73 og of containers
5c00: 2e 0a 53 74 61 72 74 69 6e 67 20 77 69 74 68 20 ..Starting with
5c10: 4f 70 65 6e 53 53 4c 20 33 2e 32 20 6f 6e 20 4d OpenSSL 3.2 on M
5c20: 53 20 57 69 6e 64 6f 77 73 2c 20 73 65 74 20 74 S Windows, set t
5c30: 6f 20 22 5b 63 6f 6e 73 74 20 22 6f 72 67 2e 6f o "[const "org.o
5c40: 70 65 6e 73 73 6c 2e 77 69 6e 73 74 6f 72 65 3a penssl.winstore:
5c50: 2f 2f 22 5d 22 0a 74 6f 20 75 73 65 20 74 68 65 //"]".to use the
5c60: 20 62 75 69 6c 74 2d 69 6e 20 4d 53 20 57 69 6e built-in MS Win
5c70: 64 6f 77 73 20 43 65 72 74 69 66 69 63 61 74 65 dows Certificate
5c80: 20 53 74 6f 72 65 2e 20 53 74 61 72 74 69 6e 67 Store. Starting
5c90: 20 69 6e 20 54 63 6c 54 4c 53 20 32 2e 30 2c 20 in TclTLS 2.0,
5ca0: 74 68 69 73 0a 69 73 20 74 68 65 20 64 65 66 61 this.is the defa
5cb0: 75 6c 74 20 69 66 20 5b 6f 70 74 69 6f 6e 20 2d ult if [option -
5cc0: 63 61 64 69 72 5d 2c 20 5b 6f 70 74 69 6f 6e 20 cadir], [option
5cd0: 2d 63 61 64 69 72 5d 2c 20 61 6e 64 20 5b 6f 70 -cadir], and [op
5ce0: 74 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 61 tion -castore] a
5cf0: 72 65 0a 6e 6f 74 20 73 70 65 63 69 66 69 65 64 re.not specified
5d00: 2e 20 54 68 69 73 20 73 74 6f 72 65 20 6f 6e 6c . This store onl
5d10: 79 20 73 75 70 70 6f 72 74 73 20 72 6f 6f 74 20 y supports root
5d20: 63 65 72 74 69 66 69 63 61 74 65 20 73 74 6f 72 certificate stor
5d30: 65 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 72 es...[opt_def -r
5d40: 65 71 75 65 73 74 20 5b 61 72 67 20 62 6f 6f 6c equest [arg bool
5d50: 5d 5d 0a 52 65 71 75 65 73 74 20 61 20 63 65 72 ]].Request a cer
5d60: 74 69 66 69 63 61 74 65 20 66 72 6f 6d 20 74 68 tificate from th
5d70: 65 20 70 65 65 72 20 64 75 72 69 6e 67 20 74 68 e peer during th
5d80: 65 20 53 53 4c 20 68 61 6e 64 73 68 61 6b 65 2e e SSL handshake.
5d90: 20 54 68 69 73 20 69 73 20 6e 65 65 64 65 64 0a This is needed.
5da0: 74 6f 20 64 6f 20 43 65 72 74 69 66 69 63 61 74 to do Certificat
5db0: 65 20 56 61 6c 69 64 61 74 69 6f 6e 2e 20 53 74 e Validation. St
5dc0: 61 72 74 69 6e 67 20 69 6e 20 54 63 6c 54 4c 53 arting in TclTLS
5dd0: 20 31 2e 38 2c 20 74 68 65 20 64 65 66 61 75 6c 1.8, the defaul
5de0: 74 20 69 73 0a 5b 63 6f 6e 73 74 20 74 72 75 65 t is.[const true
5df0: 5d 20 66 6f 72 20 63 6c 69 65 6e 74 20 63 6f 6e ] for client con
5e00: 6e 65 63 74 69 6f 6e 73 2e 20 53 74 61 72 74 69 nections. Starti
5e10: 6e 67 20 69 6e 20 54 63 6c 54 4c 53 20 32 2e 30 ng in TclTLS 2.0
5e20: 2c 20 69 66 20 73 65 74 20 74 6f 0a 5b 63 6f 6e , if set to.[con
5e30: 73 74 20 66 61 6c 73 65 5d 20 61 6e 64 20 5b 6f st false] and [o
5e40: 70 74 69 6f 6e 20 2d 72 65 71 75 69 72 65 5d 20 ption -require]
5e50: 69 73 20 5b 63 6f 6e 73 74 20 74 72 75 65 5d 2c is [const true],
5e60: 20 74 68 65 6e 20 74 68 69 73 20 77 69 6c 6c 20 then this will
5e70: 62 65 0a 6f 76 65 72 72 69 64 64 65 6e 20 74 6f be.overridden to
5e80: 20 5b 63 6f 6e 73 74 20 74 72 75 65 5d 2e 20 49 [const true]. I
5e90: 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 20 n addition, the
5ea0: 63 6c 69 65 6e 74 20 63 61 6e 20 6d 61 6e 75 61 client can manua
5eb0: 6c 6c 79 20 69 6e 73 70 65 63 74 20 61 6e 64 0a lly inspect and.
5ec0: 61 63 63 65 70 74 20 6f 72 20 72 65 6a 65 63 74 accept or reject
5ed0: 20 65 61 63 68 20 63 65 72 74 69 66 69 63 61 74 each certificat
5ee0: 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6f 70 74 e using the [opt
5ef0: 69 6f 6e 20 2d 76 61 6c 69 64 61 74 65 63 6f 6d ion -validatecom
5f00: 6d 61 6e 64 5d 20 6f 70 74 69 6f 6e 2e 0a 0a 5b mand] option...[
5f10: 6f 70 74 5f 64 65 66 20 2d 72 65 71 75 69 72 65 opt_def -require
5f20: 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 52 65 71 [arg bool]].Req
5f30: 75 69 72 65 20 61 20 76 61 6c 69 64 20 63 65 72 uire a valid cer
5f40: 74 69 66 69 63 61 74 65 20 66 72 6f 6d 20 74 68 tificate from th
5f50: 65 20 70 65 65 72 20 64 75 72 69 6e 67 20 74 68 e peer during th
5f60: 65 20 53 53 4c 20 68 61 6e 64 73 68 61 6b 65 2e e SSL handshake.
5f70: 20 49 66 20 74 68 69 73 20 69 73 0a 73 65 74 20 If this is.set
5f80: 74 6f 20 74 72 75 65 2c 20 74 68 65 6e 20 5b 6f to true, then [o
5f90: 70 74 69 6f 6e 20 2d 72 65 71 75 65 73 74 5d 20 ption -request]
5fa0: 6d 75 73 74 20 61 6c 73 6f 20 62 65 20 73 65 74 must also be set
5fb0: 20 74 6f 20 74 72 75 65 20 61 6e 64 20 61 20 65 to true and a e
5fc0: 69 74 68 65 72 0a 5b 6f 70 74 69 6f 6e 20 2d 63 ither.[option -c
5fd0: 61 64 69 72 5d 2c 20 5b 6f 70 74 69 6f 6e 20 2d adir], [option -
5fe0: 63 61 66 69 6c 65 5d 2c 20 5b 6f 70 74 69 6f 6e cafile], [option
5ff0: 20 2d 63 61 73 74 6f 72 65 5d 2c 20 6f 72 20 61 -castore], or a
6000: 20 70 6c 61 74 66 6f 72 6d 20 64 65 66 61 75 6c platform defaul
6010: 74 0a 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 t.must be provid
6020: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 76 ed in order to v
6030: 61 6c 69 64 61 74 65 20 61 67 61 69 6e 73 74 2e alidate against.
6040: 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6e 20 The default in
6050: 54 63 6c 54 4c 53 20 31 2e 38 20 61 6e 64 0a 65 TclTLS 1.8 and.e
6060: 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 arlier versions
6070: 69 73 20 5b 63 6f 6e 73 74 20 66 61 6c 73 65 5d is [const false]
6080: 20 73 69 6e 63 65 20 6e 6f 74 20 61 6c 6c 20 70 since not all p
6090: 6c 61 74 66 6f 72 6d 73 20 68 61 76 65 20 63 65 latforms have ce
60a0: 72 74 69 66 69 63 61 74 65 73 20 74 6f 0a 76 61 rtificates to.va
60b0: 6c 69 64 61 74 65 20 61 67 61 69 6e 73 74 20 69 lidate against i
60c0: 6e 20 61 20 66 6f 72 6d 20 63 6f 6d 70 61 74 69 n a form compati
60d0: 62 6c 65 20 77 69 74 68 20 4f 70 65 6e 53 53 4c ble with OpenSSL
60e0: 2e 20 53 74 61 72 74 69 6e 67 20 69 6e 20 54 63 . Starting in Tc
60f0: 6c 54 4c 53 20 32 2e 30 2c 0a 74 68 65 20 64 65 lTLS 2.0,.the de
6100: 66 61 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 fault is [const
6110: 74 72 75 65 5d 20 66 6f 72 20 63 6c 69 65 6e 74 true] for client
6120: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 0a 5b connections...[
6130: 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 73 75 62 73 list_end]..[subs
6140: 65 63 74 69 6f 6e 20 22 57 68 65 6e 20 61 72 65 ection "When are
6150: 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 20 6f 70 command line op
6160: 74 69 6f 6e 73 20 6e 65 65 64 65 64 3f 22 5d 0a tions needed?"].
6170: 0a 49 6e 20 54 63 6c 54 4c 53 20 31 2e 38 20 61 .In TclTLS 1.8 a
6180: 6e 64 20 65 61 72 6c 69 65 72 20 76 65 72 73 69 nd earlier versi
6190: 6f 6e 73 2c 20 63 65 72 74 69 66 69 63 61 74 65 ons, certificate
61a0: 20 76 61 6c 69 64 61 74 69 6f 6e 20 69 73 0a 5b validation is.[
61b0: 65 6d 70 68 20 4e 4f 54 5d 20 65 6e 61 62 6c 65 emph NOT] enable
61c0: 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 54 68 d by default. Th
61d0: 69 73 20 6c 69 6d 69 74 61 74 69 6f 6e 20 69 73 is limitation is
61e0: 20 64 75 65 20 74 6f 20 74 68 65 20 6c 61 63 6b due to the lack
61f0: 20 6f 66 20 61 20 63 6f 6d 6d 6f 6e 0a 63 72 6f of a common.cro
6200: 73 73 20 70 6c 61 74 66 6f 72 6d 20 64 61 74 61 ss platform data
6210: 62 61 73 65 20 6f 66 20 43 65 72 74 69 66 69 63 base of Certific
6220: 61 74 65 20 41 75 74 68 6f 72 69 74 79 20 28 43 ate Authority (C
6230: 41 29 20 70 72 6f 76 69 64 65 64 20 63 65 72 74 A) provided cert
6240: 69 66 69 63 61 74 65 73 20 74 6f 0a 76 61 6c 69 ificates to.vali
6250: 64 61 74 65 20 61 67 61 69 6e 73 74 2e 20 4d 61 date against. Ma
6260: 6e 79 20 4c 69 6e 75 78 20 73 79 73 74 65 6d 73 ny Linux systems
6270: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 natively suppor
6280: 74 20 4f 70 65 6e 53 53 4c 20 61 6e 64 20 74 68 t OpenSSL and th
6290: 75 73 20 68 61 76 65 0a 74 68 65 73 65 20 63 65 us have.these ce
62a0: 72 74 69 66 69 63 61 74 65 73 20 69 6e 73 74 61 rtificates insta
62b0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
62c0: 74 68 65 20 4f 53 2c 20 62 75 74 20 4d 61 63 4f the OS, but MacO
62d0: 53 20 61 6e 64 20 4d 53 20 57 69 6e 64 6f 77 73 S and MS Windows
62e0: 20 64 6f 20 6e 6f 74 2e 0a 53 74 61 72 69 6e 67 do not..Staring
62f0: 20 69 6e 20 54 63 6c 54 4c 53 20 32 2e 30 2c 20 in TclTLS 2.0,
6300: 74 68 65 20 64 65 66 61 75 6c 74 20 66 6f 72 20 the default for
6310: 63 6c 69 65 6e 74 20 63 6f 6e 6e 65 63 74 69 6f client connectio
6320: 6e 73 20 68 61 73 20 62 65 65 6e 20 63 68 61 6e ns has been chan
6330: 67 65 64 20 74 6f 0a 72 65 71 75 69 72 65 20 63 ged to.require c
6340: 65 72 74 69 66 69 63 61 74 65 20 76 61 6c 69 64 ertificate valid
6350: 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 ation by default
6360: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 75 73 . In order to us
6370: 65 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 72 e the [option -r
6380: 65 71 75 69 72 65 5d 0a 6f 70 74 69 6f 6e 2c 20 equire].option,
6390: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
63a0: 77 69 6e 67 20 6d 75 73 74 20 62 65 20 74 72 75 wing must be tru
63b0: 65 3a 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e 20 e:..[list_begin
63c0: 69 74 65 6d 69 7a 65 64 5d 0a 0a 5b 69 74 65 6d itemized]..[item
63d0: 5d 0a 4f 6e 20 4c 69 6e 75 78 20 61 6e 64 20 55 ].On Linux and U
63e0: 6e 69 78 20 73 79 73 74 65 6d 73 20 77 69 74 68 nix systems with
63f0: 20 4f 70 65 6e 53 53 4c 20 61 6c 72 65 61 64 79 OpenSSL already
6400: 20 69 6e 73 74 61 6c 6c 65 64 20 6f 72 20 69 66 installed or if
6410: 20 74 68 65 20 43 41 0a 63 65 72 74 69 66 69 63 the CA.certific
6420: 61 74 65 73 20 61 72 65 20 61 76 61 69 6c 61 62 ates are availab
6430: 6c 65 20 69 6e 20 50 45 4d 20 66 6f 72 6d 61 74 le in PEM format
6440: 2c 20 61 6e 64 20 69 66 20 74 68 65 79 20 61 72 , and if they ar
6450: 65 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a e stored in the.
6460: 73 74 61 6e 64 61 72 64 20 6c 6f 63 61 74 69 6f standard locatio
6470: 6e 73 2c 20 6f 72 20 69 66 20 74 68 65 20 5b 76 ns, or if the [v
6480: 61 72 20 53 53 4c 5f 43 45 52 54 5f 44 49 52 5d ar SSL_CERT_DIR]
6490: 20 6f 72 20 5b 76 61 72 20 53 53 4c 5f 43 45 52 or [var SSL_CER
64a0: 54 5f 46 49 4c 45 5d 0a 65 6e 76 69 72 6f 6e 6d T_FILE].environm
64b0: 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 61 72 ent variables ar
64c0: 65 20 73 65 74 2c 20 74 68 65 6e 20 5b 6f 70 74 e set, then [opt
64d0: 69 6f 6e 20 2d 63 61 64 69 72 5d 2c 20 5b 6f 70 ion -cadir], [op
64e0: 74 69 6f 6e 20 2d 63 61 64 69 72 5d 2c 0a 61 6e tion -cadir],.an
64f0: 64 20 5b 6f 70 74 69 6f 6e 20 2d 63 61 73 74 6f d [option -casto
6500: 72 65 5d 20 61 72 65 6e 27 74 20 6e 65 65 64 65 re] aren't neede
6510: 64 2e 0a 0a 5b 69 74 65 6d 5d 0a 49 66 20 4f 70 d...[item].If Op
6520: 65 6e 53 53 4c 20 69 73 20 6e 6f 74 20 69 6e 73 enSSL is not ins
6530: 74 61 6c 6c 65 64 20 69 6e 20 74 68 65 20 64 65 talled in the de
6540: 66 61 75 6c 74 20 6c 6f 63 61 74 69 6f 6e 2c 20 fault location,
6550: 6f 72 20 77 68 65 6e 20 75 73 69 6e 67 20 4d 61 or when using Ma
6560: 63 20 4f 53 0a 6f 72 20 4d 53 20 57 69 6e 64 6f c OS.or MS Windo
6570: 77 73 20 61 6e 64 20 4f 70 65 6e 53 53 4c 20 69 ws and OpenSSL i
6580: 73 20 69 6e 73 74 61 6c 6c 65 64 2c 20 74 68 65 s installed, the
6590: 20 5b 76 61 72 20 53 53 4c 5f 43 45 52 54 5f 44 [var SSL_CERT_D
65a0: 49 52 5d 20 61 6e 64 2f 6f 72 0a 5b 76 61 72 20 IR] and/or.[var
65b0: 53 53 4c 5f 43 45 52 54 5f 46 49 4c 45 5d 20 65 SSL_CERT_FILE] e
65c0: 6e 76 69 72 6f 6e 6d 65 6e 74 20 76 61 72 69 61 nvironment varia
65d0: 62 6c 65 73 20 6f 72 20 74 68 65 20 6f 6e 65 20 bles or the one
65e0: 6f 66 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d of the [option -
65f0: 63 61 64 69 72 5d 2c 0a 5b 6f 70 74 69 6f 6e 20 cadir],.[option
6600: 2d 63 61 64 69 72 5d 2c 20 6f 72 20 5b 6f 70 74 -cadir], or [opt
6610: 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f 70 ion -castore] op
6620: 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 64 65 tions must be de
6630: 66 69 6e 65 64 2e 0a 0a 5b 69 74 65 6d 5d 0a 4f fined...[item].O
6640: 6e 20 4d 53 20 57 69 6e 64 6f 77 73 2c 20 73 74 n MS Windows, st
6650: 61 72 74 69 6e 67 20 69 6e 20 4f 70 65 6e 53 53 arting in OpenSS
6660: 4c 20 33 2e 32 2c 20 69 74 20 69 73 20 6e 6f 77 L 3.2, it is now
6670: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 61 63 63 possible to acc
6680: 65 73 73 20 74 68 65 0a 62 75 69 6c 74 2d 69 6e ess the.built-in
6690: 20 57 69 6e 64 6f 77 73 20 43 65 72 74 69 66 69 Windows Certifi
66a0: 63 61 74 65 20 53 74 6f 72 65 20 66 72 6f 6d 20 cate Store from
66b0: 4f 70 65 6e 53 53 4c 2e 20 54 68 69 73 20 63 61 OpenSSL. This ca
66c0: 6e 20 62 65 20 75 74 69 6c 69 7a 65 64 20 62 79 n be utilized by
66d0: 0a 73 65 74 74 69 6e 67 20 74 68 65 20 5b 6f 70 .setting the [op
66e0: 74 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f tion -castore] o
66f0: 70 74 69 6f 6e 20 74 6f 20 22 5b 63 6f 6e 73 74 ption to "[const
6700: 20 6f 72 67 2e 6f 70 65 6e 73 73 6c 2e 77 69 6e org.openssl.win
6710: 73 74 6f 72 65 3a 2f 2f 5d 22 2e 0a 49 6e 20 54 store://]"..In T
6720: 63 6c 54 4c 53 20 32 2e 30 2c 20 74 68 69 73 20 clTLS 2.0, this
6730: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 76 is the default v
6740: 61 6c 75 65 20 69 66 20 5b 6f 70 74 69 6f 6e 20 alue if [option
6750: 2d 63 61 64 69 72 5d 2c 0a 5b 6f 70 74 69 6f 6e -cadir],.[option
6760: 20 2d 63 61 64 69 72 5d 2c 20 61 6e 64 20 5b 6f -cadir], and [o
6770: 70 74 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 ption -castore]
6780: 61 72 65 20 6e 6f 74 20 73 70 65 63 69 66 69 65 are not specifie
6790: 64 2e 0a 0a 5b 69 74 65 6d 5d 0a 49 66 20 4f 70 d...[item].If Op
67a0: 65 6e 53 53 4c 20 69 73 20 6e 6f 74 20 69 6e 73 enSSL is not ins
67b0: 74 61 6c 6c 65 64 20 6f 72 20 74 68 65 20 43 41 talled or the CA
67c0: 20 63 65 72 74 69 66 69 63 61 74 65 73 20 61 72 certificates ar
67d0: 65 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 e not available
67e0: 69 6e 20 50 45 4d 0a 66 6f 72 6d 61 74 2c 20 74 in PEM.format, t
67f0: 68 65 20 43 41 20 63 65 72 74 69 66 69 63 61 74 he CA certificat
6800: 65 73 20 6d 75 73 74 20 62 65 20 64 6f 77 6e 6c es must be downl
6810: 6f 61 64 65 64 20 61 6e 64 20 69 6e 73 74 61 6c oaded and instal
6820: 6c 65 64 20 77 69 74 68 20 74 68 65 20 75 73 65 led with the use
6830: 72 0a 73 6f 66 74 77 61 72 65 2e 20 54 68 65 20 r.software. The
6840: 43 55 52 4c 20 74 65 61 6d 20 6d 61 6b 65 73 20 CURL team makes
6850: 74 68 65 6d 20 61 76 61 69 6c 61 62 6c 65 20 61 them available a
6860: 74 0a 5b 75 72 69 20 22 68 74 74 70 73 3a 2f 2f t.[uri "https://
6870: 63 75 72 6c 2e 73 65 2f 64 6f 63 73 2f 63 61 65 curl.se/docs/cae
6880: 78 74 72 61 63 74 2e 68 74 6d 6c 22 20 22 43 41 xtract.html" "CA
6890: 20 63 65 72 74 69 66 69 63 61 74 65 73 20 65 78 certificates ex
68a0: 74 72 61 63 74 65 64 0a 66 72 6f 6d 20 4d 6f 7a tracted.from Moz
68b0: 69 6c 6c 61 22 5d 20 69 6e 20 74 68 65 20 5b 66 illa"] in the [f
68c0: 69 6c 65 20 63 61 63 65 72 74 2e 70 65 6d 5d 20 ile cacert.pem]
68d0: 66 69 6c 65 2e 20 59 6f 75 20 6d 75 73 74 20 74 file. You must t
68e0: 68 65 6e 20 65 69 74 68 65 72 20 73 65 74 20 74 hen either set t
68f0: 68 65 0a 5b 76 61 72 20 53 53 4c 5f 43 45 52 54 he.[var SSL_CERT
6900: 5f 44 49 52 5d 20 61 6e 64 2f 6f 72 20 5b 76 61 _DIR] and/or [va
6910: 72 20 53 53 4c 5f 43 45 52 54 5f 46 49 4c 45 5d r SSL_CERT_FILE]
6920: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 76 61 72 environment var
6930: 69 61 62 6c 65 73 20 6f 72 20 74 68 65 0a 5b 6f iables or the.[o
6940: 70 74 69 6f 6e 20 2d 63 61 64 69 72 5d 20 6f 72 ption -cadir] or
6950: 20 5b 6f 70 74 69 6f 6e 20 2d 63 61 66 69 6c 65 [option -cafile
6960: 5d 20 6f 70 74 69 6f 6e 73 20 74 6f 20 74 68 65 ] options to the
6970: 20 43 41 20 63 65 72 74 20 66 69 6c 65 27 73 20 CA cert file's
6980: 69 6e 73 74 61 6c 6c 0a 6c 6f 63 61 74 69 6f 6e install.location
6990: 2e 20 49 74 20 69 73 20 79 6f 75 72 20 72 65 73 . It is your res
69a0: 70 6f 6e 73 69 62 69 6c 69 74 79 20 74 6f 20 6b ponsibility to k
69b0: 65 65 70 20 74 68 69 73 20 66 69 6c 65 20 75 70 eep this file up
69c0: 20 74 6f 20 64 61 74 65 2e 0a 0a 5b 6c 69 73 74 to date...[list
69d0: 5f 65 6e 64 5d 0a 0a 5b 73 65 63 74 69 6f 6e 20 _end]..[section
69e0: 22 43 61 6c 6c 62 61 63 6b 20 4f 70 74 69 6f 6e "Callback Option
69f0: 73 22 5d 0a 0a 41 73 20 70 72 65 76 69 6f 75 73 s"]..As previous
6a00: 6c 79 20 64 65 73 63 72 69 62 65 64 2c 20 65 61 ly described, ea
6a10: 63 68 20 63 68 61 6e 6e 65 6c 20 63 61 6e 20 62 ch channel can b
6a20: 65 20 67 69 76 65 6e 20 74 68 65 69 72 20 6f 77 e given their ow
6a30: 6e 20 63 61 6c 6c 62 61 63 6b 73 0a 74 6f 20 68 n callbacks.to h
6a40: 61 6e 64 6c 65 20 69 6e 74 65 72 6d 65 64 69 61 andle intermedia
6a50: 74 65 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 te processing by
6a60: 20 74 68 65 20 4f 70 65 6e 53 53 4c 20 6c 69 62 the OpenSSL lib
6a70: 72 61 72 79 2c 20 75 73 69 6e 67 20 74 68 65 0a rary, using the.
6a80: 5b 6f 70 74 69 6f 6e 20 2d 63 6f 6d 6d 61 6e 64 [option -command
6a90: 5d 2c 20 5b 6f 70 74 69 6f 6e 20 2d 70 61 73 73 ], [option -pass
6aa0: 77 6f 72 64 5d 2c 20 61 6e 64 20 5b 6f 70 74 69 word], and [opti
6ab0: 6f 6e 20 2d 76 61 6c 69 64 61 74 65 5f 63 6f 6d on -validate_com
6ac0: 6d 61 6e 64 5d 20 6f 70 74 69 6f 6e 73 0a 70 61 mand] options.pa
6ad0: 73 73 65 64 20 74 6f 20 65 69 74 68 65 72 20 6f ssed to either o
6ae0: 66 20 5b 63 6d 64 20 74 6c 73 3a 3a 73 6f 63 6b f [cmd tls::sock
6af0: 65 74 5d 20 6f 72 20 5b 63 6d 64 20 74 6c 73 3a et] or [cmd tls:
6b00: 3a 69 6d 70 6f 72 74 5d 2e 0a 55 6e 6c 69 6b 65 :import]..Unlike
6b10: 20 70 72 65 76 69 6f 75 73 20 76 65 72 73 69 6f previous versio
6b20: 6e 73 20 6f 66 20 54 63 6c 54 4c 53 2c 20 6f 6e ns of TclTLS, on
6b30: 6c 79 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 ly if the callba
6b40: 63 6b 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 ck generates an
6b50: 65 72 72 6f 72 2c 0a 77 69 6c 6c 20 74 68 65 20 error,.will the
6b60: 5b 73 79 73 63 6d 64 20 62 67 65 72 72 6f 72 5d [syscmd bgerror]
6b70: 20 63 6f 6d 6d 61 6e 64 20 62 65 20 69 6e 76 6f command be invo
6b80: 6b 65 64 20 77 69 74 68 20 74 68 65 20 65 72 72 ked with the err
6b90: 6f 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a or information..
6ba0: 0a 5b 73 75 62 73 65 63 74 69 6f 6e 20 22 56 61 .[subsection "Va
6bb0: 6c 75 65 73 20 66 6f 72 20 43 6f 6d 6d 61 6e 64 lues for Command
6bc0: 20 43 61 6c 6c 62 61 63 6b 22 5d 0a 0a 54 68 65 Callback"]..The
6bd0: 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 74 68 callback for th
6be0: 65 20 5b 6f 70 74 69 6f 6e 20 2d 63 6f 6d 6d 61 e [option -comma
6bf0: 6e 64 5d 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e nd] option is in
6c00: 76 6f 6b 65 64 20 61 74 20 73 65 76 65 72 61 6c voked at several
6c10: 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 points during t
6c20: 68 65 0a 4f 70 65 6e 53 53 4c 20 68 61 6e 64 73 he.OpenSSL hands
6c30: 68 61 6b 65 20 61 6e 64 20 64 75 72 69 6e 67 20 hake and during
6c40: 72 6f 75 74 69 6e 65 20 6f 70 65 72 61 74 69 6f routine operatio
6c50: 6e 73 2e 20 53 65 65 20 62 65 6c 6f 77 20 66 6f ns. See below fo
6c60: 72 20 74 68 65 20 70 6f 73 73 69 62 6c 65 0a 61 r the possible.a
6c70: 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 64 20 rguments passed
6c80: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
6c90: 73 63 72 69 70 74 2e 20 56 61 6c 75 65 73 20 72 script. Values r
6ca0: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 eturned from the
6cb0: 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 69 67 callback are.ig
6cc0: 6e 6f 72 65 64 2e 0a 0a 5b 6c 69 73 74 5f 62 65 nored...[list_be
6cd0: 67 69 6e 20 6f 70 74 69 6f 6e 73 5d 0a 0a 5b 6f gin options]..[o
6ce0: 70 74 5f 64 65 66 20 65 72 72 6f 72 20 5b 61 72 pt_def error [ar
6cf0: 67 20 22 63 68 61 6e 6e 65 6c 49 64 20 6d 65 73 g "channelId mes
6d00: 73 61 67 65 22 5d 5d 0a 54 68 69 73 20 66 6f 72 sage"]].This for
6d10: 6d 20 6f 66 20 63 61 6c 6c 62 61 63 6b 20 69 73 m of callback is
6d20: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
6d30: 72 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 r an error occur
6d40: 73 20 64 75 72 69 6e 67 20 74 68 65 20 69 6e 69 s during the ini
6d50: 74 69 61 6c 0a 63 6f 6e 6e 65 63 74 69 6f 6e 2c tial.connection,
6d60: 20 68 61 6e 64 73 68 61 6b 65 2c 20 6f 72 20 49 handshake, or I
6d70: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 54 /O operations. T
6d80: 68 65 20 5b 61 72 67 20 6d 65 73 73 61 67 65 5d he [arg message]
6d90: 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 argument can be
6da0: 0a 66 72 6f 6d 20 74 68 65 20 54 63 6c 5f 45 72 .from the Tcl_Er
6db0: 72 6e 6f 4d 73 67 2c 20 4f 70 65 6e 53 53 4c 20 rnoMsg, OpenSSL
6dc0: 66 75 6e 63 74 69 6f 6e 20 5b 66 75 6e 20 45 52 function [fun ER
6dd0: 52 5f 72 65 61 73 6f 6e 5f 65 72 72 6f 72 5f 73 R_reason_error_s
6de0: 74 72 69 6e 67 28 29 5d 2c 0a 6f 72 20 61 20 63 tring()],.or a c
6df0: 75 73 74 6f 6d 20 6d 65 73 73 61 67 65 2e 20 54 ustom message. T
6e00: 68 69 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 his callback is
6e10: 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 new for TclTLS 1
6e20: 2e 38 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 69 6e .8...[opt_def in
6e30: 66 6f 20 5b 61 72 67 20 22 63 68 61 6e 6e 65 6c fo [arg "channel
6e40: 49 64 20 6d 61 6a 6f 72 20 6d 69 6e 6f 72 20 6d Id major minor m
6e50: 65 73 73 61 67 65 20 74 79 70 65 22 5d 5d 0a 54 essage type"]].T
6e60: 68 69 73 20 66 6f 72 6d 20 6f 66 20 63 61 6c 6c his form of call
6e70: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
6e80: 62 79 20 74 68 65 20 4f 70 65 6e 53 53 4c 20 66 by the OpenSSL f
6e90: 75 6e 63 74 69 6f 6e 0a 5b 66 75 6e 20 53 53 4c unction.[fun SSL
6ea0: 5f 73 65 74 5f 69 6e 66 6f 5f 63 61 6c 6c 62 61 _set_info_callba
6eb0: 63 6b 28 29 5d 20 64 75 72 69 6e 67 20 74 68 65 ck()] during the
6ec0: 20 69 6e 69 74 69 61 6c 20 63 6f 6e 6e 65 63 74 initial connect
6ed0: 69 6f 6e 20 61 6e 64 20 68 61 6e 64 73 68 61 6b ion and handshak
6ee0: 65 0a 6f 70 65 72 61 74 69 6f 6e 73 2e 20 54 68 e.operations. Th
6ef0: 65 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 3a e arguments are:
6f00: 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e 20 64 65 ..[list_begin de
6f10: 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a 5b 64 65 66 finitions]..[def
6f20: 20 5b 61 72 67 20 6d 61 6a 6f 72 5d 5d 0a 4d 61 [arg major]].Ma
6f30: 6a 6f 72 20 63 61 74 65 67 6f 72 79 20 66 6f 72 jor category for
6f40: 20 65 72 72 6f 72 2e 20 56 61 6c 69 64 20 65 6e error. Valid en
6f50: 75 6d 73 20 61 72 65 3a 20 5b 63 6f 6e 73 74 20 ums are: [const
6f60: 68 61 6e 64 73 68 61 6b 65 5d 2c 20 5b 63 6f 6e handshake], [con
6f70: 73 74 20 61 6c 65 72 74 5d 2c 0a 5b 63 6f 6e 73 st alert],.[cons
6f80: 74 20 63 6f 6e 6e 65 63 74 5d 2c 20 5b 63 6f 6e t connect], [con
6f90: 73 74 20 61 63 63 65 70 74 5d 2e 0a 0a 5b 64 65 st accept]...[de
6fa0: 66 20 5b 61 72 67 20 6d 69 6e 6f 72 5d 5d 0a 4d f [arg minor]].M
6fb0: 69 6e 6f 72 20 63 61 74 65 67 6f 72 79 20 66 6f inor category fo
6fc0: 72 20 65 72 72 6f 72 2e 20 56 61 6c 69 64 20 65 r error. Valid e
6fd0: 6e 75 6d 73 20 61 72 65 3a 20 5b 63 6f 6e 73 74 nums are: [const
6fe0: 20 73 74 61 72 74 5d 2c 20 5b 63 6f 6e 73 74 20 start], [const
6ff0: 64 6f 6e 65 5d 2c 20 5b 63 6f 6e 73 74 20 72 65 done], [const re
7000: 61 64 5d 2c 0a 5b 63 6f 6e 73 74 20 77 72 69 74 ad],.[const writ
7010: 65 5d 2c 20 5b 63 6f 6e 73 74 20 6c 6f 6f 70 5d e], [const loop]
7020: 2c 20 5b 63 6f 6e 73 74 20 65 78 69 74 5d 2e 0a , [const exit]..
7030: 0a 5b 64 65 66 20 5b 61 72 67 20 6d 65 73 73 61 .[def [arg messa
7040: 67 65 5d 5d 0a 44 65 73 63 72 69 70 74 69 76 65 ge]].Descriptive
7050: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
7060: 77 68 69 63 68 20 6d 61 79 20 62 65 20 67 65 6e which may be gen
7070: 65 72 61 74 65 64 20 65 69 74 68 65 72 20 62 79 erated either by
7080: 0a 5b 66 75 6e 20 53 53 4c 5f 73 74 61 74 65 5f .[fun SSL_state_
7090: 73 74 72 69 6e 67 5f 6c 6f 6e 67 28 29 5d 20 6f string_long()] o
70a0: 72 20 5b 66 75 6e 20 53 53 4c 5f 61 6c 65 72 74 r [fun SSL_alert
70b0: 5f 64 65 73 63 5f 73 74 72 69 6e 67 5f 6c 6f 6e _desc_string_lon
70c0: 67 28 29 5d 2c 0a 64 65 70 65 6e 64 69 6e 67 20 g()],.depending
70d0: 6f 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 2e 0a on the context..
70e0: 0a 5b 64 65 66 20 5b 61 72 67 20 74 79 70 65 5d .[def [arg type]
70f0: 5d 0a 46 6f 72 20 61 6c 65 72 74 73 2c 20 74 68 ].For alerts, th
7100: 65 20 70 6f 73 73 69 62 6c 65 20 76 61 6c 75 65 e possible value
7110: 73 20 61 72 65 3a 20 5b 63 6f 6e 73 74 20 77 61 s are: [const wa
7120: 72 6e 69 6e 67 5d 2c 0a 5b 63 6f 6e 73 74 20 66 rning],.[const f
7130: 61 74 61 6c 5d 2c 20 61 6e 64 20 5b 63 6f 6e 73 atal], and [cons
7140: 74 20 75 6e 6b 6e 6f 77 6e 5d 2e 20 46 6f 72 20 t unknown]. For
7150: 6f 74 68 65 72 73 2c 20 5b 63 6f 6e 73 74 20 69 others, [const i
7160: 6e 66 6f 5d 20 69 73 20 75 73 65 64 2e 0a 54 68 nfo] is used..Th
7170: 69 73 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e is argument is n
7180: 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e ew for TclTLS 1.
7190: 38 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 8...[list_end]..
71a0: 5b 6f 70 74 5f 64 65 66 20 6d 65 73 73 61 67 65 [opt_def message
71b0: 20 5b 61 72 67 20 22 63 68 61 6e 6e 65 6c 49 64 [arg "channelId
71c0: 20 64 69 72 65 63 74 69 6f 6e 20 76 65 72 73 69 direction versi
71d0: 6f 6e 20 63 6f 6e 74 65 6e 74 5f 74 79 70 65 20 on content_type
71e0: 6d 65 73 73 61 67 65 22 5d 5d 0a 54 68 69 73 20 message"]].This
71f0: 66 6f 72 6d 20 6f 66 20 63 61 6c 6c 62 61 63 6b form of callback
7200: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 is invoked by t
7210: 68 65 20 4f 70 65 6e 53 53 4c 20 66 75 6e 63 74 he OpenSSL funct
7220: 69 6f 6e 0a 5b 66 75 6e 20 53 53 4c 5f 73 65 74 ion.[fun SSL_set
7230: 5f 6d 73 67 5f 63 61 6c 6c 62 61 63 6b 28 29 5d _msg_callback()]
7240: 20 77 68 65 6e 65 76 65 72 20 61 20 6d 65 73 73 whenever a mess
7250: 61 67 65 20 69 73 20 73 65 6e 74 20 6f 72 20 72 age is sent or r
7260: 65 63 65 69 76 65 64 20 64 75 72 69 6e 67 20 74 eceived during t
7270: 68 65 0a 69 6e 69 74 69 61 6c 20 63 6f 6e 6e 65 he.initial conne
7280: 63 74 69 6f 6e 2c 20 68 61 6e 64 73 68 61 6b 65 ction, handshake
7290: 2c 20 6f 72 20 49 2f 4f 20 6f 70 65 72 61 74 69 , or I/O operati
72a0: 6f 6e 73 2e 20 49 74 20 69 73 20 6f 6e 6c 79 20 ons. It is only
72b0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 0a 4f available when.O
72c0: 70 65 6e 53 53 4c 20 69 73 20 63 6f 6d 70 6c 69 penSSL is compli
72d0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 63 6f 6e ed with the [con
72e0: 73 74 20 65 6e 61 62 6c 65 2d 73 73 6c 2d 74 72 st enable-ssl-tr
72f0: 61 63 65 5d 20 6f 70 74 69 6f 6e 2e 20 54 68 69 ace] option. Thi
7300: 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 6e 65 s callback is.ne
7310: 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e 38 w for TclTLS 1.8
7320: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 73 20 . The arguments
7330: 61 72 65 3a 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 are:..[list_begi
7340: 6e 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a n definitions]..
7350: 5b 64 65 66 20 5b 61 72 67 20 64 69 72 65 63 74 [def [arg direct
7360: 69 6f 6e 5d 5d 0a 44 69 72 65 63 74 69 6f 6e 20 ion]].Direction
7370: 69 73 20 65 69 74 68 65 72 20 5b 63 6f 6e 73 74 is either [const
7380: 20 53 65 6e 74 5d 20 6f 72 20 5b 63 6f 6e 73 74 Sent] or [const
7390: 20 52 65 63 65 69 76 65 64 5d 2e 0a 0a 5b 64 65 Received]...[de
73a0: 66 20 5b 61 72 67 20 76 65 72 73 69 6f 6e 5d 5d f [arg version]]
73b0: 0a 56 65 72 73 69 6f 6e 20 69 73 20 74 68 65 20 .Version is the
73c0: 70 72 6f 74 6f 63 6f 6c 20 76 65 72 73 69 6f 6e protocol version
73d0: 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 63 6f 6e ...[def [arg con
73e0: 74 65 6e 74 5f 74 79 70 65 5d 5d 0a 43 6f 6e 74 tent_type]].Cont
73f0: 65 6e 74 20 74 79 70 65 20 69 73 20 74 68 65 20 ent type is the
7400: 6d 65 73 73 61 67 65 20 63 6f 6e 74 65 6e 74 20 message content
7410: 74 79 70 65 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 type...[def [arg
7420: 20 6d 65 73 73 61 67 65 5d 5d 0a 4d 65 73 73 61 message]].Messa
7430: 67 65 20 69 73 20 6d 6f 72 65 20 69 6e 66 6f 20 ge is more info
7440: 66 72 6f 6d 20 74 68 65 20 5b 63 6f 6e 73 74 20 from the [const
7450: 53 53 4c 5f 74 72 61 63 65 5d 20 41 50 49 2e 0a SSL_trace] API..
7460: 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 6f 70 .[list_end]..[op
7470: 74 5f 64 65 66 20 73 65 73 73 69 6f 6e 20 5b 61 t_def session [a
7480: 72 67 20 22 63 68 61 6e 6e 65 6c 49 64 20 73 65 rg "channelId se
7490: 73 73 69 6f 6e 5f 69 64 20 73 65 73 73 69 6f 6e ssion_id session
74a0: 5f 74 69 63 6b 65 74 20 6c 69 66 65 74 69 6d 65 _ticket lifetime
74b0: 22 5d 5d 0a 54 68 69 73 20 66 6f 72 6d 20 6f 66 "]].This form of
74c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
74d0: 6f 6b 65 64 20 62 79 20 74 68 65 20 4f 70 65 6e oked by the Open
74e0: 53 53 4c 20 66 75 6e 63 74 69 6f 6e 0a 5b 66 75 SSL function.[fu
74f0: 6e 20 53 53 4c 5f 43 54 58 5f 73 65 73 73 5f 73 n SSL_CTX_sess_s
7500: 65 74 5f 6e 65 77 5f 63 62 28 29 5d 20 77 68 65 et_new_cb()] whe
7510: 6e 65 76 65 72 20 61 20 6e 65 77 20 73 65 73 73 never a new sess
7520: 69 6f 6e 20 69 64 20 69 73 20 73 65 6e 74 20 62 ion id is sent b
7530: 79 20 74 68 65 0a 73 65 72 76 65 72 20 64 75 72 y the.server dur
7540: 69 6e 67 20 74 68 65 20 69 6e 69 74 69 61 6c 20 ing the initial
7550: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 68 connection and h
7560: 61 6e 64 73 68 61 6b 65 20 61 6e 64 20 61 6c 73 andshake and als
7570: 6f 20 64 75 72 69 6e 67 20 74 68 65 20 73 65 73 o during the ses
7580: 73 69 6f 6e 0a 69 66 20 74 68 65 20 5b 6f 70 74 sion.if the [opt
7590: 69 6f 6e 20 2d 70 6f 73 74 5f 68 61 6e 64 73 68 ion -post_handsh
75a0: 61 6b 65 5d 20 6f 70 74 69 6f 6e 20 69 73 20 73 ake] option is s
75b0: 65 74 20 74 6f 20 74 72 75 65 2e 20 54 68 69 73 et to true. This
75c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 77 callback is new
75d0: 20 66 6f 72 0a 54 63 6c 54 4c 53 20 31 2e 38 2e for.TclTLS 1.8.
75e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 73 20 61 The arguments a
75f0: 72 65 3a 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e re:..[list_begin
7600: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a 5b definitions]..[
7610: 64 65 66 20 5b 61 72 67 20 73 65 73 73 69 6f 6e def [arg session
7620: 5f 69 64 5d 5d 0a 53 65 73 73 69 6f 6e 20 49 64 _id]].Session Id
7630: 20 69 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 is the current
7640: 73 65 73 73 69 6f 6e 20 69 64 65 6e 74 69 66 69 session identifi
7650: 65 72 0a 0a 5b 64 65 66 20 5b 61 72 67 20 73 65 er..[def [arg se
7660: 73 73 69 6f 6e 5f 74 69 63 6b 65 74 5d 5d 0a 54 ssion_ticket]].T
7670: 69 63 6b 65 74 20 69 73 20 74 68 65 20 73 65 73 icket is the ses
7680: 73 69 6f 6e 20 74 69 63 6b 65 74 20 69 6e 66 6f sion ticket info
7690: 0a 0a 5b 64 65 66 20 5b 61 72 67 20 6c 69 66 65 ..[def [arg life
76a0: 74 69 6d 65 5d 5d 0a 4c 69 66 65 74 69 6d 65 20 time]].Lifetime
76b0: 69 73 20 74 68 65 20 74 69 63 6b 65 74 20 6c 69 is the ticket li
76c0: 66 65 74 69 6d 65 20 69 6e 20 73 65 63 6f 6e 64 fetime in second
76d0: 73 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a s...[list_end]..
76e0: 5b 6f 70 74 5f 64 65 66 20 76 65 72 69 66 79 20 [opt_def verify
76f0: 5b 61 72 67 20 22 63 68 61 6e 6e 65 6c 49 64 20 [arg "channelId
7700: 64 65 70 74 68 20 63 65 72 74 20 73 74 61 74 75 depth cert statu
7710: 73 20 65 72 72 6f 72 22 5d 5d 0a 54 68 69 73 20 s error"]].This
7720: 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 6d 6f 76 callback was mov
7730: 65 64 20 74 6f 20 5b 6f 70 74 69 6f 6e 20 2d 76 ed to [option -v
7740: 61 6c 69 64 61 74 65 63 6f 6d 6d 61 6e 64 5d 20 alidatecommand]
7750: 69 6e 20 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a in TclTLS 1.8...
7760: 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 73 75 62 [list_end]..[sub
7770: 73 65 63 74 69 6f 6e 20 22 56 61 6c 75 65 73 20 section "Values
7780: 66 6f 72 20 50 61 73 73 77 6f 72 64 20 43 61 6c for Password Cal
7790: 6c 62 61 63 6b 22 5d 0a 0a 54 68 65 20 63 61 6c lback"]..The cal
77a0: 6c 62 61 63 6b 20 66 6f 72 20 74 68 65 20 5b 6f lback for the [o
77b0: 70 74 69 6f 6e 20 2d 70 61 73 73 77 6f 72 64 5d ption -password]
77c0: 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b option is invok
77d0: 65 64 20 62 79 20 54 63 6c 54 4c 53 20 77 68 65 ed by TclTLS whe
77e0: 6e 65 76 65 72 20 4f 70 65 6e 53 53 4c 20 6e 65 never OpenSSL ne
77f0: 65 64 73 0a 74 6f 20 6f 62 74 61 69 6e 20 61 20 eds.to obtain a
7800: 70 61 73 73 77 6f 72 64 2e 20 53 65 65 20 62 65 password. See be
7810: 6c 6f 77 20 66 6f 72 20 74 68 65 20 70 6f 73 73 low for the poss
7820: 69 62 6c 65 20 61 72 67 75 6d 65 6e 74 73 20 70 ible arguments p
7830: 61 73 73 65 64 20 74 6f 20 74 68 65 0a 63 61 6c assed to the.cal
7840: 6c 62 61 63 6b 20 73 63 72 69 70 74 2e 20 54 68 lback script. Th
7850: 65 20 75 73 65 72 20 70 72 6f 76 69 64 65 64 20 e user provided
7860: 70 61 73 73 77 6f 72 64 20 69 73 20 65 78 70 65 password is expe
7870: 63 74 65 64 20 74 6f 20 62 65 20 72 65 74 75 72 cted to be retur
7880: 6e 65 64 20 62 79 20 74 68 65 0a 63 61 6c 6c 62 ned by the.callb
7890: 61 63 6b 2e 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 ack...[list_begi
78a0: 6e 20 6f 70 74 69 6f 6e 73 5d 0a 0a 5b 6f 70 74 n options]..[opt
78b0: 5f 64 65 66 20 70 61 73 73 77 6f 72 64 20 5b 61 _def password [a
78c0: 72 67 20 22 72 77 66 6c 61 67 20 73 69 7a 65 22 rg "rwflag size"
78d0: 5d 5d 0a 49 6e 76 6f 6b 65 64 20 77 68 65 6e 20 ]].Invoked when
78e0: 6c 6f 61 64 69 6e 67 20 6f 72 20 73 74 6f 72 69 loading or stori
78f0: 6e 67 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 ng an encrypted
7900: 50 45 4d 20 63 65 72 74 69 66 69 63 61 74 65 2e PEM certificate.
7910: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 73 20 61 The arguments a
7920: 72 65 3a 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e re:..[list_begin
7930: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a 5b definitions]..[
7940: 64 65 66 20 5b 61 72 67 20 72 77 66 6c 61 67 5d def [arg rwflag]
7950: 5d 0a 54 68 65 20 72 65 61 64 2f 77 72 69 74 65 ].The read/write
7960: 20 66 6c 61 67 20 69 73 20 30 20 66 6f 72 20 72 flag is 0 for r
7970: 65 61 64 69 6e 67 2f 64 65 63 72 79 70 74 69 6f eading/decryptio
7980: 6e 20 6f 72 20 31 20 66 6f 72 20 77 72 69 74 69 n or 1 for writi
7990: 6e 67 2f 65 6e 63 72 79 70 74 69 6f 6e 2e 0a 54 ng/encryption..T
79a0: 68 65 20 6c 61 74 74 65 72 20 63 61 6e 20 62 65 he latter can be
79b0: 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 used to determi
79c0: 6e 65 20 77 68 65 6e 20 74 6f 20 70 72 6f 6d 70 ne when to promp
79d0: 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 6f t the user to co
79e0: 6e 66 69 72 6d 2e 0a 54 68 69 73 20 61 72 67 75 nfirm..This argu
79f0: 6d 65 6e 74 20 69 73 20 6e 65 77 20 66 6f 72 20 ment is new for
7a00: 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 64 65 TclTLS 1.8...[de
7a10: 66 20 5b 61 72 67 20 73 69 7a 65 5d 5d 0a 54 68 f [arg size]].Th
7a20: 65 20 73 69 7a 65 20 69 73 20 74 68 65 20 6d 61 e size is the ma
7a30: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
7a40: 74 68 65 20 70 61 73 73 77 6f 72 64 20 69 6e 20 the password in
7a50: 62 79 74 65 73 2e 0a 54 68 69 73 20 61 72 67 75 bytes..This argu
7a60: 6d 65 6e 74 20 69 73 20 6e 65 77 20 66 6f 72 20 ment is new for
7a70: 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 6c 69 TclTLS 1.8...[li
7a80: 73 74 5f 65 6e 64 5d 0a 0a 5b 6c 69 73 74 5f 65 st_end]..[list_e
7a90: 6e 64 5d 0a 0a 5b 73 75 62 73 65 63 74 69 6f 6e nd]..[subsection
7aa0: 20 22 56 61 6c 75 65 73 20 66 6f 72 20 56 61 6c "Values for Val
7ab0: 69 64 61 74 65 20 43 6f 6d 6d 61 6e 64 20 43 61 idate Command Ca
7ac0: 6c 6c 62 61 63 6b 22 5d 0a 0a 54 68 65 20 63 61 llback"]..The ca
7ad0: 6c 6c 62 61 63 6b 20 66 6f 72 20 74 68 65 20 5b llback for the [
7ae0: 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 64 61 74 65 option -validate
7af0: 63 6f 6d 6d 61 6e 64 5d 20 6f 70 74 69 6f 6e 20 command] option
7b00: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
7b10: 67 20 74 68 65 20 68 61 6e 64 73 68 61 6b 65 0a g the handshake.
7b20: 70 72 6f 63 65 73 73 20 69 6e 20 6f 72 64 65 72 process in order
7b30: 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 for the applica
7b40: 74 69 6f 6e 20 74 6f 20 76 61 6c 69 64 61 74 65 tion to validate
7b50: 20 74 68 65 20 70 72 6f 76 69 64 65 64 20 76 61 the provided va
7b60: 6c 75 65 28 73 29 2e 20 53 65 65 0a 62 65 6c 6f lue(s). See.belo
7b70: 77 20 66 6f 72 20 74 68 65 20 70 6f 73 73 69 62 w for the possib
7b80: 6c 65 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73 le arguments pas
7b90: 73 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 sed to the callb
7ba0: 61 63 6b 20 73 63 72 69 70 74 2e 20 49 66 20 6e ack script. If n
7bb0: 6f 74 0a 73 70 65 63 69 66 69 65 64 2c 20 4f 70 ot.specified, Op
7bc0: 65 6e 53 53 4c 20 77 69 6c 6c 20 61 63 63 65 70 enSSL will accep
7bd0: 74 20 61 6c 6c 20 76 61 6c 69 64 20 63 65 72 74 t all valid cert
7be0: 69 66 69 63 61 74 65 73 20 61 6e 64 20 65 78 74 ificates and ext
7bf0: 65 6e 73 69 6f 6e 73 2e 20 54 6f 20 72 65 6a 65 ensions. To reje
7c00: 63 74 0a 74 68 65 20 76 61 6c 75 65 20 61 6e 64 ct.the value and
7c10: 20 61 62 6f 72 74 20 74 68 65 20 63 6f 6e 6e 65 abort the conne
7c20: 63 74 69 6f 6e 2c 20 74 68 65 20 63 61 6c 6c 62 ction, the callb
7c30: 61 63 6b 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ack should retur
7c40: 6e 20 30 2e 20 54 6f 20 61 63 63 65 70 74 20 74 n 0. To accept t
7c50: 68 65 0a 76 61 6c 75 65 20 61 6e 64 20 63 6f 6e he.value and con
7c60: 74 69 6e 75 65 20 74 68 65 20 63 6f 6e 6e 65 63 tinue the connec
7c70: 74 69 6f 6e 2c 20 69 74 20 73 68 6f 75 6c 64 20 tion, it should
7c80: 72 65 74 75 72 6e 20 31 2e 20 54 6f 20 72 65 6a return 1. To rej
7c90: 65 63 74 20 74 68 65 20 76 61 6c 75 65 2c 20 62 ect the value, b
7ca0: 75 74 0a 63 6f 6e 74 69 6e 75 65 20 74 68 65 20 ut.continue the
7cb0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 69 74 20 73 connection, it s
7cc0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 32 2e 20 hould return 2.
7cd0: 54 68 69 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 This callback is
7ce0: 20 6e 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 new for TclTLS
7cf0: 31 2e 38 2e 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 1.8...[list_begi
7d00: 6e 20 6f 70 74 69 6f 6e 73 5d 0a 0a 5b 6f 70 74 n options]..[opt
7d10: 5f 64 65 66 20 61 6c 70 6e 20 5b 61 72 67 20 22 _def alpn [arg "
7d20: 63 68 61 6e 6e 65 6c 49 64 20 70 72 6f 74 6f 63 channelId protoc
7d30: 6f 6c 20 6d 61 74 63 68 22 5d 5d 0a 46 6f 72 20 ol match"]].For
7d40: 73 65 72 76 65 72 73 2c 20 74 68 69 73 20 66 6f servers, this fo
7d50: 72 6d 20 6f 66 20 63 61 6c 6c 62 61 63 6b 20 69 rm of callback i
7d60: 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 s invoked when t
7d70: 68 65 20 63 6c 69 65 6e 74 20 41 4c 50 4e 20 65 he client ALPN e
7d80: 78 74 65 6e 73 69 6f 6e 20 69 73 0a 72 65 63 65 xtension is.rece
7d90: 69 76 65 64 2e 20 49 66 20 5b 61 72 67 20 6d 61 ived. If [arg ma
7da0: 74 63 68 5d 20 69 73 20 74 72 75 65 2c 20 74 68 tch] is true, th
7db0: 65 6e 20 5b 61 72 67 20 70 72 6f 74 6f 63 6f 6c en [arg protocol
7dc0: 5d 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 5b ] is the first.[
7dd0: 6f 70 74 69 6f 6e 20 2d 61 6c 70 6e 5d 20 70 72 option -alpn] pr
7de0: 6f 74 6f 63 6f 6c 20 6f 70 74 69 6f 6e 20 69 6e otocol option in
7df0: 20 63 6f 6d 6d 6f 6e 20 74 6f 20 62 6f 74 68 20 common to both
7e00: 74 68 65 20 63 6c 69 65 6e 74 20 61 6e 64 20 73 the client and s
7e10: 65 72 76 65 72 2e 0a 49 66 20 6e 6f 74 2c 20 74 erver..If not, t
7e20: 68 65 20 66 69 72 73 74 20 63 6c 69 65 6e 74 20 he first client
7e30: 73 70 65 63 69 66 69 65 64 20 70 72 6f 74 6f 63 specified protoc
7e40: 6f 6c 20 69 73 20 75 73 65 64 2e 20 54 68 69 73 ol is used. This
7e50: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6c callback is cal
7e60: 6c 65 64 0a 61 66 74 65 72 20 74 68 65 20 48 65 led.after the He
7e70: 6c 6c 6f 20 61 6e 64 20 53 4e 49 20 63 61 6c 6c llo and SNI call
7e80: 62 61 63 6b 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 backs...[opt_def
7e90: 20 68 65 6c 6c 6f 20 5b 61 72 67 20 22 63 68 61 hello [arg "cha
7ea0: 6e 6e 65 6c 49 64 20 73 65 72 76 65 72 6e 61 6d nnelId servernam
7eb0: 65 20 73 65 73 73 69 6f 6e 5f 69 64 22 5d 5d 0a e session_id"]].
7ec0: 46 6f 72 20 73 65 72 76 65 72 73 2c 20 74 68 69 For servers, thi
7ed0: 73 20 66 6f 72 6d 20 6f 66 20 63 61 6c 6c 62 61 s form of callba
7ee0: 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 ck is invoked du
7ef0: 72 69 6e 67 20 63 6c 69 65 6e 74 20 68 65 6c 6c ring client hell
7f00: 6f 20 6d 65 73 73 61 67 65 0a 70 72 6f 63 65 73 o message.proces
7f10: 73 69 6e 67 2e 20 54 68 65 20 70 75 72 70 6f 73 sing. The purpos
7f20: 65 20 69 73 20 73 6f 20 74 68 65 20 73 65 72 76 e is so the serv
7f30: 65 72 20 63 61 6e 20 73 65 6c 65 63 74 20 74 68 er can select th
7f40: 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 63 65 e appropriate ce
7f50: 72 74 69 66 69 63 61 74 65 0a 74 6f 20 70 72 65 rtificate.to pre
7f60: 73 65 6e 74 20 74 6f 20 74 68 65 20 63 6c 69 65 sent to the clie
7f70: 6e 74 2c 20 61 6e 64 20 74 6f 20 6d 61 6b 65 20 nt, and to make
7f80: 6f 74 68 65 72 20 63 6f 6e 66 69 67 75 72 61 74 other configurat
7f90: 69 6f 6e 20 61 64 6a 75 73 74 6d 65 6e 74 73 20 ion adjustments
7fa0: 72 65 6c 65 76 61 6e 74 0a 74 6f 20 74 68 61 74 relevant.to that
7fb0: 20 73 65 72 76 65 72 20 6e 61 6d 65 20 61 6e 64 server name and
7fc0: 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 its configurati
7fd0: 6f 6e 2e 20 49 74 20 69 73 20 63 61 6c 6c 65 64 on. It is called
7fe0: 20 62 65 66 6f 72 65 20 74 68 65 20 53 4e 49 20 before the SNI
7ff0: 61 6e 64 20 41 4c 50 4e 0a 63 61 6c 6c 62 61 63 and ALPN.callbac
8000: 6b 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 73 6e ks...[opt_def sn
8010: 69 20 5b 61 72 67 20 22 63 68 61 6e 6e 65 6c 49 i [arg "channelI
8020: 64 20 73 65 72 76 65 72 6e 61 6d 65 22 5d 5d 0a d servername"]].
8030: 46 6f 72 20 73 65 72 76 65 72 73 2c 20 74 68 69 For servers, thi
8040: 73 20 66 6f 72 6d 20 6f 66 20 63 61 6c 6c 62 61 s form of callba
8050: 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 ck is invoked wh
8060: 65 6e 20 74 68 65 20 53 65 72 76 65 72 20 4e 61 en the Server Na
8070: 6d 65 20 49 6e 64 69 63 61 74 69 6f 6e 0a 28 53 me Indication.(S
8080: 4e 49 29 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 NI) extension is
8090: 20 72 65 63 65 69 76 65 64 2e 20 54 68 65 20 5b received. The [
80a0: 61 72 67 20 73 65 72 76 65 72 6e 61 6d 65 5d 20 arg servername]
80b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
80c0: 63 6c 69 65 6e 74 0a 70 72 6f 76 69 64 65 64 20 client.provided
80d0: 73 65 72 76 65 72 20 6e 61 6d 65 20 73 70 65 63 server name spec
80e0: 69 66 69 65 64 20 69 6e 20 74 68 65 20 5b 6f 70 ified in the [op
80f0: 74 69 6f 6e 20 2d 73 65 72 76 65 72 6e 61 6d 65 tion -servername
8100: 5d 20 6f 70 74 69 6f 6e 2e 20 54 68 65 0a 70 75 ] option. The.pu
8110: 72 70 6f 73 65 20 69 73 20 73 6f 20 77 68 65 6e rpose is so when
8120: 20 61 20 73 65 72 76 65 72 20 73 75 70 70 6f 72 a server suppor
8130: 74 73 20 6d 75 6c 74 69 70 6c 65 20 6e 61 6d 65 ts multiple name
8140: 73 2c 20 74 68 65 20 72 69 67 68 74 20 63 65 72 s, the right cer
8150: 74 69 66 69 63 61 74 65 0a 63 61 6e 20 62 65 20 tificate.can be
8160: 75 73 65 64 2e 20 49 74 20 69 73 20 63 61 6c 6c used. It is call
8170: 65 64 20 61 66 74 65 72 20 74 68 65 20 48 65 6c ed after the Hel
8180: 6c 6f 20 63 61 6c 6c 62 61 63 6b 20 62 75 74 20 lo callback but
8190: 62 65 66 6f 72 65 20 74 68 65 20 41 4c 50 4e 0a before the ALPN.
81a0: 63 61 6c 6c 62 61 63 6b 2e 0a 0a 5b 6f 70 74 5f callback...[opt_
81b0: 64 65 66 20 76 65 72 69 66 79 20 5b 61 72 67 20 def verify [arg
81c0: 22 63 68 61 6e 6e 65 6c 49 64 20 64 65 70 74 68 "channelId depth
81d0: 20 63 65 72 74 20 73 74 61 74 75 73 20 65 72 72 cert status err
81e0: 6f 72 22 5d 5d 0a 54 68 69 73 20 66 6f 72 6d 20 or"]].This form
81f0: 6f 66 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 of callback is i
8200: 6e 76 6f 6b 65 64 20 62 79 20 4f 70 65 6e 53 53 nvoked by OpenSS
8210: 4c 20 77 68 65 6e 20 61 20 6e 65 77 20 63 65 72 L when a new cer
8220: 74 69 66 69 63 61 74 65 20 69 73 20 72 65 63 65 tificate is rece
8230: 69 76 65 64 0a 66 72 6f 6d 20 74 68 65 20 70 65 ived.from the pe
8240: 65 72 2e 20 49 74 20 61 6c 6c 6f 77 73 20 74 68 er. It allows th
8250: 65 20 63 6c 69 65 6e 74 20 74 6f 20 63 68 65 63 e client to chec
8260: 6b 20 74 68 65 20 63 65 72 74 69 66 69 63 61 74 k the certificat
8270: 65 20 76 65 72 69 66 69 63 61 74 69 6f 6e 0a 72 e verification.r
8280: 65 73 75 6c 74 73 20 61 6e 64 20 63 68 6f 6f 73 esults and choos
8290: 65 20 77 68 65 74 68 65 72 20 74 6f 20 63 6f 6e e whether to con
82a0: 74 69 6e 75 65 20 6f 72 20 6e 6f 74 2e 20 49 74 tinue or not. It
82b0: 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 65 is called for e
82c0: 61 63 68 0a 63 65 72 74 69 66 69 63 61 74 65 20 ach.certificate
82d0: 69 6e 20 74 68 65 20 63 65 72 74 69 66 69 63 61 in the certifica
82e0: 74 65 20 63 68 61 69 6e 2e 20 54 68 69 73 20 63 te chain. This c
82f0: 61 6c 6c 62 61 63 6b 20 77 61 73 20 6d 6f 76 65 allback was move
8300: 64 20 66 72 6f 6d 0a 5b 6f 70 74 69 6f 6e 20 2d d from.[option -
8310: 63 6f 6d 6d 61 6e 64 5d 20 69 6e 20 54 63 6c 54 command] in TclT
8320: 4c 53 20 31 2e 38 2e 20 54 68 65 20 61 72 67 75 LS 1.8. The argu
8330: 6d 65 6e 74 73 20 61 72 65 3a 0a 0a 5b 6c 69 73 ments are:..[lis
8340: 74 5f 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 t_begin definiti
8350: 6f 6e 73 5d 0a 0a 5b 64 65 66 20 5b 61 72 67 20 ons]..[def [arg
8360: 64 65 70 74 68 5d 5d 0a 54 68 65 20 64 65 70 74 depth]].The dept
8370: 68 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 h is the integer
8380: 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 63 65 depth of the ce
8390: 72 74 69 66 69 63 61 74 65 20 69 6e 20 74 68 65 rtificate in the
83a0: 20 63 65 72 74 69 66 69 63 61 74 65 20 63 68 61 certificate cha
83b0: 69 6e 2c 0a 77 68 65 72 65 20 30 20 69 73 20 74 in,.where 0 is t
83c0: 68 65 20 70 65 65 72 20 63 65 72 74 69 66 69 63 he peer certific
83d0: 61 74 65 20 61 6e 64 20 68 69 67 68 65 72 20 76 ate and higher v
83e0: 61 6c 75 65 73 20 67 6f 69 6e 67 20 75 70 20 74 alues going up t
83f0: 6f 20 74 68 65 20 43 65 72 74 69 66 69 63 61 74 o the Certificat
8400: 65 0a 41 75 74 68 6f 72 69 74 79 20 28 43 41 29 e.Authority (CA)
8410: 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 63 65 72 ...[def [arg cer
8420: 74 5d 5d 0a 54 68 65 20 63 65 72 74 20 61 72 67 t]].The cert arg
8430: 75 6d 65 6e 74 20 69 73 20 61 20 6c 69 73 74 20 ument is a list
8440: 6f 66 20 6b 65 79 2d 76 61 6c 75 65 20 70 61 69 of key-value pai
8450: 72 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 rs similar to th
8460: 6f 73 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a ose returned by.
8470: 5b 63 6d 64 20 74 6c 73 3a 3a 73 74 61 74 75 73 [cmd tls::status
8480: 5d 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 73 74 ]...[def [arg st
8490: 61 74 75 73 5d 5d 0a 54 68 65 20 73 74 61 74 75 atus]].The statu
84a0: 73 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 s argument is th
84b0: 65 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 69 64 69 e boolean validi
84c0: 74 79 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e ty of the curren
84d0: 74 20 63 65 72 74 69 66 69 63 61 74 65 20 77 68 t certificate wh
84e0: 65 72 65 20 30 0a 69 73 20 69 6e 76 61 6c 69 64 ere 0.is invalid
84f0: 20 61 6e 64 20 31 20 69 73 20 76 61 6c 69 64 2e and 1 is valid.
8500: 0a 0a 5b 64 65 66 20 5b 61 72 67 20 65 72 72 6f ..[def [arg erro
8510: 72 5d 5d 0a 54 68 65 20 65 72 72 6f 72 20 61 72 r]].The error ar
8520: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 65 72 gument is the er
8530: 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 69 66 20 ror message, if
8540: 61 6e 79 2c 20 67 65 6e 65 72 61 74 65 64 20 62 any, generated b
8550: 79 0a 5b 66 75 6e 20 58 35 30 39 5f 53 54 4f 52 y.[fun X509_STOR
8560: 45 5f 43 54 58 5f 67 65 74 5f 65 72 72 6f 72 28 E_CTX_get_error(
8570: 29 5d 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a )]...[list_end].
8580: 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 52 65 66 .[list_end]..Ref
8590: 65 72 65 6e 63 65 20 69 6d 70 6c 65 6d 65 6e 74 erence implement
85a0: 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 ations of these
85b0: 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 70 72 callbacks are pr
85c0: 6f 76 69 64 65 64 20 69 6e 20 5b 66 69 6c 65 20 ovided in [file
85d0: 74 6c 73 2e 74 63 6c 5d 0a 61 73 20 5b 63 6d 64 tls.tcl].as [cmd
85e0: 20 74 6c 73 3a 3a 63 61 6c 6c 62 61 63 6b 5d 2c tls::callback],
85f0: 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 61 73 73 77 [cmd tls::passw
8600: 6f 72 64 5d 2c 20 61 6e 64 20 5b 63 6d 64 20 74 ord], and [cmd t
8610: 6c 73 3a 3a 76 61 6c 69 64 61 74 65 5f 63 6f 6d ls::validate_com
8620: 6d 61 6e 64 5d 0a 72 65 73 70 65 63 74 69 76 65 mand].respective
8630: 6c 79 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 ly. Note that th
8640: 65 73 65 20 61 72 65 20 6f 6e 6c 79 20 5b 65 6d ese are only [em
8650: 70 68 20 73 61 6d 70 6c 65 5d 20 69 6d 70 6c 65 ph sample] imple
8660: 6d 65 6e 74 61 74 69 6f 6e 73 2e 20 49 6e 20 61 mentations. In a
8670: 20 6d 6f 72 65 0a 72 65 61 6c 69 73 74 69 63 20 more.realistic
8680: 64 65 70 6c 6f 79 6d 65 6e 74 20 79 6f 75 20 77 deployment you w
8690: 6f 75 6c 64 20 73 70 65 63 69 66 79 20 79 6f 75 ould specify you
86a0: 72 20 6f 77 6e 20 63 61 6c 6c 62 61 63 6b 20 73 r own callback s
86b0: 63 72 69 70 74 73 20 6f 6e 20 65 61 63 68 20 54 cripts on each T
86c0: 4c 53 0a 63 68 61 6e 6e 65 6c 20 75 73 69 6e 67 LS.channel using
86d0: 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 63 6f the [option -co
86e0: 6d 6d 61 6e 64 5d 2c 20 5b 6f 70 74 69 6f 6e 20 mmand], [option
86f0: 2d 70 61 73 73 77 6f 72 64 5d 2c 20 61 6e 64 0a -password], and.
8700: 5b 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 64 61 74 [option -validat
8710: 65 5f 63 6f 6d 6d 61 6e 64 5d 20 6f 70 74 69 6f e_command] optio
8720: 6e 73 2e 0a 0a 5b 70 61 72 61 5d 0a 0a 54 68 65 ns...[para]..The
8730: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
8740: 72 20 77 68 65 6e 20 74 68 65 20 5b 6f 70 74 69 r when the [opti
8750: 6f 6e 20 2d 63 6f 6d 6d 61 6e 64 5d 20 61 6e 64 on -command] and
8760: 20 5b 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 64 61 [option -valida
8770: 74 65 5f 63 6f 6d 6d 61 6e 64 5d 0a 6f 70 74 69 te_command].opti
8780: 6f 6e 73 20 61 72 65 20 6e 6f 74 20 73 70 65 63 ons are not spec
8790: 69 66 69 65 64 2c 20 69 73 20 66 6f 72 20 54 63 ified, is for Tc
87a0: 6c 54 4c 53 20 74 6f 20 70 72 6f 63 65 73 73 20 lTLS to process
87b0: 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6c the associated l
87c0: 69 62 72 61 72 79 0a 63 61 6c 6c 62 61 63 6b 73 ibrary.callbacks
87d0: 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 54 68 65 internally. The
87e0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
87f0: 72 20 77 68 65 6e 20 74 68 65 20 5b 6f 70 74 69 r when the [opti
8800: 6f 6e 20 2d 70 61 73 73 77 6f 72 64 5d 20 6f 70 on -password] op
8810: 74 69 6f 6e 0a 69 73 20 6e 6f 74 20 73 70 65 63 tion.is not spec
8820: 69 66 69 65 64 20 69 73 20 66 6f 72 20 54 63 6c ified is for Tcl
8830: 54 4c 53 20 74 6f 20 70 72 6f 63 65 73 73 20 74 TLS to process t
8840: 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6c 69 he associated li
8850: 62 72 61 72 79 20 63 61 6c 6c 62 61 63 6b 73 20 brary callbacks
8860: 62 79 0a 61 74 74 65 6d 70 74 69 6e 67 20 74 6f by.attempting to
8870: 20 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a call [cmd tls::
8880: 70 61 73 73 77 6f 72 64 5d 2e 20 54 68 65 20 64 password]. The d
8890: 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 ifference betwee
88a0: 6e 20 74 68 65 73 65 20 74 77 6f 0a 62 65 68 61 n these two.beha
88b0: 76 69 6f 72 73 20 69 73 20 61 20 63 6f 6e 73 65 viors is a conse
88c0: 71 75 65 6e 63 65 20 6f 66 20 6d 61 69 6e 74 61 quence of mainta
88d0: 69 6e 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c ining compatibil
88e0: 69 74 79 20 77 69 74 68 20 65 61 72 6c 69 65 72 ity with earlier
88f0: 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 .implementations
8900: 2e 0a 0a 5b 70 61 72 61 5d 0a 0a 5b 65 6d 70 68 ...[para]..[emph
8910: 20 22 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 "The use of the
8920: 20 72 65 66 65 72 65 6e 63 65 20 63 61 6c 6c 62 reference callb
8930: 61 63 6b 73 20 5b 63 6d 64 20 74 6c 73 3a 3a 63 acks [cmd tls::c
8940: 61 6c 6c 62 61 63 6b 5d 2c 20 5b 63 6d 64 20 74 allback], [cmd t
8950: 6c 73 3a 3a 70 61 73 73 77 6f 72 64 5d 2c 0a 61 ls::password],.a
8960: 6e 64 20 5b 63 6d 64 20 74 6c 73 3a 3a 76 61 6c nd [cmd tls::val
8970: 69 64 61 74 65 5f 63 6f 6d 6d 61 6e 64 5d 20 69 idate_command] i
8980: 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 s not recommende
8990: 64 2e 20 54 68 65 79 20 6d 61 79 20 62 65 20 72 d. They may be r
89a0: 65 6d 6f 76 65 64 20 66 72 6f 6d 20 66 75 74 75 emoved from futu
89b0: 72 65 20 72 65 6c 65 61 73 65 73 2e 22 5d 0a 0a re releases."]..
89c0: 5b 73 65 63 74 69 6f 6e 20 44 65 62 75 67 5d 0a [section Debug].
89d0: 0a 46 6f 72 20 6d 6f 73 74 20 64 65 62 75 67 67 .For most debugg
89e0: 69 6e 67 20 6e 65 65 64 73 2c 20 74 68 65 20 5b ing needs, the [
89f0: 6f 70 74 69 6f 6e 20 2d 63 61 6c 6c 62 61 63 6b option -callback
8a00: 5d 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 ] option can be
8a10: 75 73 65 64 20 74 6f 20 70 72 6f 76 69 64 65 0a used to provide.
8a20: 73 75 66 66 69 63 69 65 6e 74 20 69 6e 73 69 67 sufficient insig
8a30: 68 74 20 61 6e 64 20 69 6e 66 6f 72 6d 61 74 69 ht and informati
8a40: 6f 6e 20 6f 6e 20 74 68 65 20 54 4c 53 20 68 61 on on the TLS ha
8a50: 6e 64 73 68 61 6b 65 20 61 6e 64 20 70 72 6f 67 ndshake and prog
8a60: 72 65 73 73 2e 20 49 66 0a 66 75 72 74 68 65 72 ress. If.further
8a70: 20 74 72 6f 75 62 6c 65 73 68 6f 6f 74 69 6e 67 troubleshooting
8a80: 20 69 6e 73 69 67 68 74 20 69 73 20 6e 65 65 64 insight is need
8a90: 65 64 2c 20 74 68 65 20 63 6f 6d 70 69 6c 65 20 ed, the compile
8aa0: 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 5b 6f 70 74 time option.[opt
8ab0: 69 6f 6e 20 2d 2d 65 6e 61 62 6c 65 2d 64 65 62 ion --enable-deb
8ac0: 75 67 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 ug] can be used
8ad0: 74 6f 20 67 65 74 20 64 65 74 61 69 6c 65 64 20 to get detailed
8ae0: 65 78 65 63 75 74 69 6f 6e 20 66 6c 6f 77 20 73 execution flow s
8af0: 74 61 74 75 73 2e 0a 0a 5b 70 61 72 61 5d 0a 0a tatus...[para]..
8b00: 54 4c 53 20 6b 65 79 20 6c 6f 67 67 69 6e 67 20 TLS key logging
8b10: 63 61 6e 20 62 65 20 65 6e 61 62 6c 65 64 20 62 can be enabled b
8b20: 79 20 73 65 74 74 69 6e 67 20 74 68 65 20 65 6e y setting the en
8b30: 76 69 72 6f 6e 6d 65 6e 74 20 76 61 72 69 61 62 vironment variab
8b40: 6c 65 0a 5b 76 61 72 20 53 53 4c 4b 45 59 4c 4f le.[var SSLKEYLO
8b50: 47 46 49 4c 45 5d 20 74 6f 20 74 68 65 20 6e 61 GFILE] to the na
8b60: 6d 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 74 me of the file t
8b70: 6f 20 6c 6f 67 20 74 6f 2e 20 54 68 65 6e 20 77 o log to. Then w
8b80: 68 65 6e 65 76 65 72 20 54 4c 53 20 6b 65 79 0a henever TLS key.
8b90: 6d 61 74 65 72 69 61 6c 20 69 73 20 67 65 6e 65 material is gene
8ba0: 72 61 74 65 64 20 6f 72 20 72 65 63 65 69 76 65 rated or receive
8bb0: 64 20 69 74 20 77 69 6c 6c 20 62 65 20 6c 6f 67 d it will be log
8bc0: 67 65 64 20 74 6f 20 74 68 65 20 66 69 6c 65 2e ged to the file.
8bd0: 20 54 68 69 73 20 69 73 20 75 73 65 66 75 6c 0a This is useful.
8be0: 66 6f 72 20 6c 6f 67 67 69 6e 67 20 6b 65 79 20 for logging key
8bf0: 64 61 74 61 20 66 6f 72 20 6e 65 74 77 6f 72 6b data for network
8c00: 20 6c 6f 67 67 69 6e 67 20 74 6f 6f 6c 73 20 74 logging tools t
8c10: 6f 20 75 73 65 20 74 6f 20 64 65 63 72 79 70 74 o use to decrypt
8c20: 20 74 68 65 20 64 61 74 61 2e 0a 0a 5b 70 61 72 the data...[par
8c30: 61 5d 0a 0a 54 68 65 20 5b 76 61 72 20 74 6c 73 a]..The [var tls
8c40: 3a 3a 64 65 62 75 67 5d 20 76 61 72 69 61 62 6c ::debug] variabl
8c50: 65 20 70 72 6f 76 69 64 65 73 20 73 6f 6d 65 20 e provides some
8c60: 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
8c70: 6f 6c 20 6f 76 65 72 20 74 68 65 0a 64 65 62 75 ol over the.debu
8c80: 67 20 6c 6f 67 67 69 6e 67 20 69 6e 20 74 68 65 g logging in the
8c90: 20 5b 63 6d 64 20 74 6c 73 3a 3a 63 61 6c 6c 62 [cmd tls::callb
8ca0: 61 63 6b 5d 2c 20 5b 63 6d 64 20 74 6c 73 3a 3a ack], [cmd tls::
8cb0: 70 61 73 73 77 6f 72 64 5d 2c 20 61 6e 64 0a 5b password], and.[
8cc0: 63 6d 64 20 74 6c 73 3a 3a 76 61 6c 69 64 61 74 cmd tls::validat
8cd0: 65 5f 63 6f 6d 6d 61 6e 64 5d 20 64 65 66 61 75 e_command] defau
8ce0: 6c 74 20 68 61 6e 64 6c 65 72 73 20 69 6e 20 5b lt handlers in [
8cf0: 66 69 6c 65 20 74 6c 73 2e 74 63 6c 5d 2e 0a 54 file tls.tcl]..T
8d00: 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
8d10: 20 69 73 20 30 20 77 69 74 68 20 68 69 67 68 65 is 0 with highe
8d20: 72 20 76 61 6c 75 65 73 20 70 72 6f 64 75 63 69 r values produci
8d30: 6e 67 20 6d 6f 72 65 20 64 69 61 67 6e 6f 73 74 ng more diagnost
8d40: 69 63 20 6f 75 74 70 75 74 2c 0a 61 6e 64 20 77 ic output,.and w
8d50: 69 6c 6c 20 61 6c 73 6f 20 66 6f 72 63 65 20 74 ill also force t
8d60: 68 65 20 76 65 72 69 66 79 20 6d 65 74 68 6f 64 he verify method
8d70: 20 69 6e 20 5b 63 6d 64 20 74 6c 73 3a 3a 63 61 in [cmd tls::ca
8d80: 6c 6c 62 61 63 6b 5d 20 74 6f 20 61 63 63 65 70 llback] to accep
8d90: 74 20 74 68 65 0a 63 65 72 74 69 66 69 63 61 74 t the.certificat
8da0: 65 2c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 e, even if it is
8db0: 20 69 6e 76 61 6c 69 64 20 77 68 65 6e 20 74 68 invalid when th
8dc0: 65 20 5b 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 64 e [option -valid
8dd0: 61 74 65 63 6f 6d 6d 61 6e 64 5d 0a 6f 70 74 69 atecommand].opti
8de0: 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 5b 63 6d on is set to [cm
8df0: 64 20 74 6c 73 3a 3a 76 61 6c 69 64 61 74 65 5f d tls::validate_
8e00: 63 6f 6d 6d 61 6e 64 5d 2e 0a 0a 5b 70 61 72 61 command]...[para
8e10: 5d 0a 0a 5b 65 6d 70 68 20 22 54 68 65 20 75 73 ]..[emph "The us
8e20: 65 20 6f 66 20 74 68 65 20 76 61 72 69 61 62 6c e of the variabl
8e30: 65 20 5b 76 61 72 20 74 6c 73 3a 3a 64 65 62 75 e [var tls::debu
8e40: 67 5d 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d g] is not recomm
8e50: 65 6e 64 65 64 2e 0a 49 74 20 6d 61 79 20 62 65 ended..It may be
8e60: 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 66 75 removed from fu
8e70: 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 22 5d ture releases."]
8e80: 0a 0a 5b 73 65 63 74 69 6f 6e 20 22 45 78 61 6d ..[section "Exam
8e90: 70 6c 65 73 22 5d 0a 0a 54 68 65 20 66 6f 6c 6c ples"]..The foll
8ea0: 6f 77 69 6e 67 20 61 72 65 20 65 78 61 6d 70 6c owing are exampl
8eb0: 65 20 73 63 72 69 70 74 73 20 74 6f 20 64 6f 77 e scripts to dow
8ec0: 6e 6c 6f 61 64 20 61 20 77 65 62 70 61 67 65 20 nload a webpage
8ed0: 61 6e 64 20 66 69 6c 65 20 75 73 69 6e 67 20 74 and file using t
8ee0: 68 65 0a 68 74 74 70 20 70 61 63 6b 61 67 65 2e he.http package.
8ef0: 20 53 65 65 20 5b 73 65 63 74 72 65 66 20 22 43 See [sectref "C
8f00: 65 72 74 69 66 69 63 61 74 65 20 56 61 6c 69 64 ertificate Valid
8f10: 61 74 69 6f 6e 22 5d 20 66 6f 72 20 77 68 65 6e ation"] for when
8f20: 20 74 68 65 0a 5b 6f 70 74 69 6f 6e 20 2d 63 61 the.[option -ca
8f30: 64 69 72 5d 2c 20 5b 6f 70 74 69 6f 6e 20 2d 63 dir], [option -c
8f40: 61 66 69 6c 65 5d 2c 20 61 6e 64 20 5b 6f 70 74 afile], and [opt
8f50: 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f 70 ion -castore] op
8f60: 74 69 6f 6e 73 20 61 72 65 20 61 6c 73 6f 0a 6e tions are also.n
8f70: 65 65 64 65 64 2e 20 53 65 65 20 74 68 65 20 5b eeded. See the [
8f80: 66 69 6c 65 20 64 65 6d 6f 73 5d 20 64 69 72 65 file demos] dire
8f90: 63 74 6f 72 79 20 66 6f 72 20 6d 6f 72 65 20 65 ctory for more e
8fa0: 78 61 6d 70 6c 65 20 73 63 72 69 70 74 73 2e 0a xample scripts..
8fb0: 0a 5b 70 61 72 61 5d 0a 0a 45 78 61 6d 70 6c 65 .[para]..Example
8fc0: 20 23 31 3a 20 44 6f 77 6e 6c 6f 61 64 20 61 20 #1: Download a
8fd0: 77 65 62 20 70 61 67 65 0a 0a 5b 65 78 61 6d 70 web page..[examp
8fe0: 6c 65 20 7b 0a 0a 70 61 63 6b 61 67 65 20 72 65 le {..package re
8ff0: 71 75 69 72 65 20 68 74 74 70 0a 70 61 63 6b 61 quire http.packa
9000: 67 65 20 72 65 71 75 69 72 65 20 74 6c 73 0a 0a ge require tls..
9010: 73 65 74 20 75 72 6c 20 22 68 74 74 70 73 3a 2f set url "https:/
9020: 2f 77 77 77 2e 74 63 6c 2e 74 6b 2f 22 0a 68 74 /www.tcl.tk/".ht
9030: 74 70 3a 3a 72 65 67 69 73 74 65 72 20 68 74 74 tp::register htt
9040: 70 73 20 34 34 33 20 5b 6c 69 73 74 20 3a 3a 74 ps 443 [list ::t
9050: 6c 73 3a 3a 73 6f 63 6b 65 74 20 2d 61 75 74 6f ls::socket -auto
9060: 73 65 72 76 65 72 6e 61 6d 65 20 31 20 2d 72 65 servername 1 -re
9070: 71 75 69 72 65 20 31 5d 0a 0a 23 20 47 65 74 20 quire 1]..# Get
9080: 55 52 4c 0a 73 65 74 20 74 6f 6b 65 6e 20 5b 68 URL.set token [h
9090: 74 74 70 3a 3a 67 65 74 75 72 6c 20 24 75 72 6c ttp::geturl $url
90a0: 5d 0a 0a 23 20 43 68 65 63 6b 20 66 6f 72 20 65 ]..# Check for e
90b0: 72 72 6f 72 0a 69 66 20 7b 5b 68 74 74 70 3a 3a rror.if {[http::
90c0: 73 74 61 74 75 73 20 24 74 6f 6b 65 6e 5d 20 6e status $token] n
90d0: 65 20 22 6f 6b 22 7d 20 7b 0a 20 20 20 20 70 75 e "ok"} {. pu
90e0: 74 73 20 5b 66 6f 72 6d 61 74 20 22 45 72 72 6f ts [format "Erro
90f0: 72 20 25 73 22 20 5b 68 74 74 70 3a 3a 73 74 61 r %s" [http::sta
9100: 74 75 73 20 24 74 6f 6b 65 6e 5d 5d 0a 7d 0a 0a tus $token]].}..
9110: 23 20 53 61 76 65 20 77 65 62 20 70 61 67 65 20 # Save web page
9120: 74 6f 20 66 69 6c 65 0a 73 65 74 20 63 68 20 5b to file.set ch [
9130: 6f 70 65 6e 20 65 78 61 6d 70 6c 65 2e 68 74 6d open example.htm
9140: 6c 20 77 62 5d 0a 70 75 74 73 20 24 63 68 20 5b l wb].puts $ch [
9150: 68 74 74 70 3a 3a 64 61 74 61 20 24 74 6f 6b 65 http::data $toke
9160: 6e 5d 0a 63 6c 6f 73 65 20 24 63 68 0a 0a 23 20 n].close $ch..#
9170: 43 6c 65 61 6e 75 70 0a 3a 3a 68 74 74 70 3a 3a Cleanup.::http::
9180: 63 6c 65 61 6e 75 70 20 24 74 6f 6b 65 6e 0a 7d cleanup $token.}
9190: 5d 0a 0a 45 78 61 6d 70 6c 65 20 23 32 3a 20 44 ]..Example #2: D
91a0: 6f 77 6e 6c 6f 61 64 20 61 20 66 69 6c 65 0a 0a ownload a file..
91b0: 5b 65 78 61 6d 70 6c 65 20 7b 0a 0a 70 61 63 6b [example {..pack
91c0: 61 67 65 20 72 65 71 75 69 72 65 20 68 74 74 70 age require http
91d0: 0a 70 61 63 6b 61 67 65 20 72 65 71 75 69 72 65 .package require
91e0: 20 74 6c 73 0a 0a 73 65 74 20 75 72 6c 20 22 68 tls..set url "h
91f0: 74 74 70 73 3a 2f 2f 77 69 6b 69 2e 74 63 6c 2d ttps://wiki.tcl-
9200: 6c 61 6e 67 2e 6f 72 67 2f 73 69 74 65 6d 61 70 lang.org/sitemap
9210: 2e 78 6d 6c 22 0a 68 74 74 70 3a 3a 72 65 67 69 .xml".http::regi
9220: 73 74 65 72 20 68 74 74 70 73 20 34 34 33 20 5b ster https 443 [
9230: 6c 69 73 74 20 3a 3a 74 6c 73 3a 3a 73 6f 63 6b list ::tls::sock
9240: 65 74 20 2d 61 75 74 6f 73 65 72 76 65 72 6e 61 et -autoserverna
9250: 6d 65 20 31 20 2d 72 65 71 75 69 72 65 20 31 5d me 1 -require 1]
9260: 0a 0a 23 20 4f 70 65 6e 20 6f 75 74 70 75 74 20 ..# Open output
9270: 66 69 6c 65 0a 73 65 74 20 66 69 6c 65 6e 61 6d file.set filenam
9280: 65 20 5b 66 69 6c 65 20 74 61 69 6c 20 24 75 72 e [file tail $ur
9290: 6c 5d 0a 73 65 74 20 63 68 20 5b 6f 70 65 6e 20 l].set ch [open
92a0: 24 66 69 6c 65 6e 61 6d 65 20 77 62 5d 0a 0a 23 $filename wb]..#
92b0: 20 47 65 74 20 66 69 6c 65 0a 73 65 74 20 74 6f Get file.set to
92c0: 6b 65 6e 20 5b 3a 3a 68 74 74 70 3a 3a 67 65 74 ken [::http::get
92d0: 75 72 6c 20 24 75 72 6c 20 2d 62 6c 6f 63 6b 73 url $url -blocks
92e0: 69 7a 65 20 36 35 35 33 36 20 2d 63 68 61 6e 6e ize 65536 -chann
92f0: 65 6c 20 24 63 68 5d 0a 0a 23 20 43 68 65 63 6b el $ch]..# Check
9300: 20 66 6f 72 20 65 72 72 6f 72 0a 69 66 20 7b 5b for error.if {[
9310: 68 74 74 70 3a 3a 73 74 61 74 75 73 20 24 74 6f http::status $to
9320: 6b 65 6e 5d 20 6e 65 20 22 6f 6b 22 7d 20 7b 0a ken] ne "ok"} {.
9330: 20 20 20 20 70 75 74 73 20 5b 66 6f 72 6d 61 74 puts [format
9340: 20 22 45 72 72 6f 72 20 25 73 22 20 5b 68 74 74 "Error %s" [htt
9350: 70 3a 3a 73 74 61 74 75 73 20 24 74 6f 6b 65 6e p::status $token
9360: 5d 5d 0a 7d 0a 0a 23 20 43 6c 65 61 6e 75 70 0a ]].}..# Cleanup.
9370: 63 6c 6f 73 65 20 24 63 68 0a 3a 3a 68 74 74 70 close $ch.::http
9380: 3a 3a 63 6c 65 61 6e 75 70 20 24 74 6f 6b 65 6e ::cleanup $token
9390: 0a 7d 5d 0a 0a 5b 73 65 63 74 69 6f 6e 20 22 53 .}]..[section "S
93a0: 70 65 63 69 61 6c 20 43 6f 6e 73 69 64 65 72 61 pecial Considera
93b0: 74 69 6f 6e 73 22 5d 0a 0a 54 68 65 20 63 61 70 tions"]..The cap
93c0: 61 62 69 6c 69 74 69 65 73 20 6f 66 20 74 68 69 abilities of thi
93d0: 73 20 70 61 63 6b 61 67 65 20 63 61 6e 20 76 61 s package can va
93e0: 72 79 20 65 6e 6f 72 6d 6f 75 73 6c 79 20 62 61 ry enormously ba
93f0: 73 65 64 20 75 70 6f 6e 20 68 6f 77 20 74 68 65 sed upon how the
9400: 0a 6c 69 6e 6b 65 64 20 74 6f 20 4f 70 65 6e 53 .linked to OpenS
9410: 53 4c 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 SL library was c
9420: 6f 6e 66 69 67 75 72 65 64 20 61 6e 64 20 62 75 onfigured and bu
9430: 69 6c 74 2e 20 4e 65 77 20 76 65 72 73 69 6f 6e ilt. New version
9440: 73 20 6d 61 79 20 6f 62 73 6f 6c 65 74 65 0a 6f s may obsolete.o
9450: 6c 64 65 72 20 70 72 6f 74 6f 63 6f 6c 20 76 65 lder protocol ve
9460: 72 73 69 6f 6e 73 2c 20 61 64 64 20 6f 72 20 72 rsions, add or r
9470: 65 6d 6f 76 65 20 63 69 70 68 65 72 73 2c 20 63 emove ciphers, c
9480: 68 61 6e 67 65 20 64 65 66 61 75 6c 74 20 76 61 hange default va
9490: 6c 75 65 73 2c 20 65 74 63 2e 0a 55 73 65 20 74 lues, etc..Use t
94a0: 68 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 72 6f he [cmd tls::pro
94b0: 74 6f 63 6f 6c 73 5d 20 63 6f 6d 6d 61 6e 64 20 tocols] command
94c0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 73 75 to obtain the su
94d0: 70 70 6f 72 74 65 64 0a 70 72 6f 74 6f 63 6f 6c pported.protocol
94e0: 20 76 65 72 73 69 6f 6e 73 2e 0a 0a 5b 73 65 63 versions...[sec
94f0: 74 69 6f 6e 20 22 45 72 72 6f 72 20 4d 65 73 73 tion "Error Mess
9500: 61 67 65 73 22 5d 0a 0a 53 6f 6d 65 20 4f 70 73 ages"]..Some Ops
9510: 6e 53 53 6c 20 65 72 72 6f 72 20 6d 65 73 73 61 nSSl error messa
9520: 67 65 73 20 68 61 76 65 20 63 72 79 70 74 69 63 ges have cryptic
9530: 20 6d 65 61 6e 69 6e 67 73 2e 20 54 68 69 73 20 meanings. This
9540: 69 73 20 61 20 6c 69 73 74 20 6f 66 20 6d 65 73 is a list of mes
9550: 73 61 67 65 73 0a 61 6c 6f 6e 67 20 77 69 74 68 sages.along with
9560: 20 74 68 65 69 72 20 74 72 75 65 20 6d 65 61 6e their true mean
9570: 69 6e 67 2e 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 ing...[list_begi
9580: 6e 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a n definitions]..
9590: 5b 64 65 66 20 5b 61 72 67 20 22 70 61 63 6b 65 [def [arg "packe
95a0: 74 20 6c 65 6e 67 74 68 20 74 6f 6f 20 6c 6f 6e t length too lon
95b0: 67 22 5d 5d 0a 43 6c 69 65 6e 74 20 68 61 73 20 g"]].Client has
95c0: 74 72 69 65 64 20 74 6f 20 63 6f 6e 6e 65 63 74 tried to connect
95d0: 20 74 6f 20 61 20 48 54 54 50 20 73 65 72 76 65 to a HTTP serve
95e0: 72 20 6f 6e 20 74 68 65 20 70 6c 61 69 6e 2d 74 r on the plain-t
95f0: 65 78 74 20 70 6f 72 74 20 69 6e 73 74 65 61 64 ext port instead
9600: 20 6f 66 20 74 68 65 20 53 53 4c 2f 54 4c 53 20 of the SSL/TLS
9610: 70 6f 72 74 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 port...[def [arg
9620: 20 22 75 6e 65 78 70 65 63 74 65 64 20 65 6f 66 "unexpected eof
9630: 20 77 68 69 6c 65 20 72 65 61 64 69 6e 67 22 5d while reading"]
9640: 5d 0a 50 65 65 72 20 68 61 73 20 63 6c 6f 73 65 ].Peer has close
9650: 64 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e d the connection
9660: 20 77 69 74 68 6f 75 74 20 73 65 6e 64 69 6e 67 without sending
9670: 20 74 68 65 20 22 63 6c 6f 73 65 20 6e 6f 74 69 the "close noti
9680: 66 79 22 20 73 68 75 74 64 6f 77 6e 20 61 6c 65 fy" shutdown ale
9690: 72 74 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 22 rt...[def [arg "
96a0: 77 72 6f 6e 67 20 76 65 72 73 69 6f 6e 20 6e 75 wrong version nu
96b0: 6d 62 65 72 22 5d 5d 0a 43 6c 69 65 6e 74 20 68 mber"]].Client h
96c0: 61 73 20 74 72 69 65 64 20 74 6f 20 63 6f 6e 6e as tried to conn
96d0: 65 63 74 20 74 6f 20 61 20 6e 6f 6e 2d 48 54 54 ect to a non-HTT
96e0: 50 20 73 65 72 76 65 72 20 6f 6e 20 61 20 6e 6f P server on a no
96f0: 6e 2d 54 4c 53 20 28 69 2e 65 2e 20 70 6c 61 69 n-TLS (i.e. plai
9700: 6e 20 74 65 78 74 29 20 70 6f 72 74 2e 0a 0a 5b n text) port...[
9710: 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 6d 61 6e 70 list_end]..[manp
9720: 61 67 65 5f 65 6e 64 5d 0a age_end].