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 73 ript access to s
0350: 65 63 75 72 65 20 73 6f 63 6b 65 74 20 63 6f 6d ecure socket com
0360: 6d 75 6e 69 63 61 74 69 6f 6e 73 0a 75 73 69 6e munications.usin
0370: 67 20 74 68 65 20 54 72 61 6e 73 70 6f 72 74 20 g the Transport
0380: 4c 61 79 65 72 20 53 65 63 75 72 69 74 79 20 28 Layer Security (
0390: 54 4c 53 29 20 70 72 6f 74 6f 63 6f 6c 2e 20 49 TLS) protocol. I
03a0: 74 20 70 72 6f 76 69 64 65 73 20 61 20 67 65 6e t provides a gen
03b0: 65 72 69 63 0a 62 69 6e 64 69 6e 67 20 74 6f 20 eric.binding to
03c0: 5b 75 72 69 20 22 68 74 74 70 73 3a 2f 2f 77 77 [uri "https://ww
03d0: 77 2e 6f 70 65 6e 73 73 6c 2e 6f 72 67 2f 22 20 w.openssl.org/"
03e0: 4f 70 65 6e 53 53 4c 5d 2c 20 75 74 69 6c 69 7a OpenSSL], utiliz
03f0: 69 6e 67 20 74 68 65 0a 5b 73 79 73 63 6d 64 20 ing the.[syscmd
0400: 54 63 6c 5f 53 74 61 63 6b 43 68 61 6e 6e 65 6c Tcl_StackChannel
0410: 5d 20 41 50 49 20 69 6e 20 54 43 4c 20 38 2e 34 ] API in TCL 8.4
0420: 20 61 6e 64 20 68 69 67 68 65 72 2e 0a 54 68 65 and higher..The
0430: 73 65 20 73 6f 63 6b 65 74 73 20 62 65 68 61 76 se sockets behav
0440: 65 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 e exactly the sa
0450: 6d 65 20 61 73 20 63 68 61 6e 6e 65 6c 73 20 63 me as channels c
0460: 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 reated using the
0470: 20 62 75 69 6c 74 2d 69 6e 0a 5b 73 79 73 63 6d built-in.[syscm
0480: 64 20 73 6f 63 6b 65 74 5d 20 63 6f 6d 6d 61 6e d socket] comman
0490: 64 2c 20 61 6c 6f 6e 67 20 77 69 74 68 20 61 64 d, along with ad
04a0: 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 ditional options
04b0: 20 66 6f 72 20 63 6f 6e 74 72 6f 6c 6c 69 6e 67 for controlling
04c0: 0a 74 68 65 20 53 53 4c 2f 54 4c 53 20 73 65 73 .the SSL/TLS ses
04d0: 73 69 6f 6e 2e 0a 0a 5b 73 65 63 74 69 6f 6e 20 sion...[section
04e0: 43 6f 6d 6d 61 6e 64 73 5d 0a 0a 54 79 70 69 63 Commands]..Typic
04f0: 61 6c 6c 79 20 6f 6e 65 20 77 6f 75 6c 64 20 75 ally one would u
0500: 73 65 20 74 68 65 20 5b 63 6d 64 20 74 6c 73 3a se the [cmd tls:
0510: 3a 73 6f 63 6b 65 74 5d 20 63 6f 6d 6d 61 6e 64 :socket] command
0520: 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 to create a new
0530: 20 65 6e 63 72 79 70 74 65 64 0a 54 43 50 20 73 encrypted.TCP s
0540: 6f 63 6b 65 74 2e 20 49 74 20 69 73 20 63 6f 6d ocket. It is com
0550: 70 61 74 69 62 6c 65 20 77 69 74 68 20 74 68 65 patible with the
0560: 20 6e 61 74 69 76 65 20 54 43 4c 20 5b 73 79 73 native TCL [sys
0570: 63 6d 64 20 3a 3a 73 6f 63 6b 65 74 5d 20 63 6f cmd ::socket] co
0580: 6d 6d 61 6e 64 2e 0a 41 6c 74 65 72 6e 61 74 69 mmand..Alternati
0590: 76 65 6c 79 20 66 6f 72 20 61 6e 20 65 78 69 73 vely for an exis
05a0: 74 69 6e 67 20 54 43 50 20 73 6f 63 6b 65 74 2c ting TCP socket,
05b0: 20 74 68 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 69 the [cmd tls::i
05c0: 6d 70 6f 72 74 5d 20 63 6f 6d 6d 61 6e 64 20 63 mport] command c
05d0: 61 6e 20 62 65 0a 75 73 65 64 20 74 6f 20 73 74 an be.used to st
05e0: 61 72 74 20 54 4c 53 20 6f 6e 20 74 68 65 20 63 art TLS on the c
05f0: 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 0a 5b 6c 69 73 onnection...[lis
0600: 74 5f 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 t_begin definiti
0610: 6f 6e 73 5d 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 ons]..[call [cmd
0620: 20 74 6c 73 3a 3a 69 6e 69 74 5d 20 5b 6f 70 74 tls::init] [opt
0630: 20 5b 61 72 67 20 2d 6f 70 74 69 6f 6e 5d 5d 20 [arg -option]]
0640: 5b 6f 70 74 20 5b 61 72 67 20 76 61 6c 75 65 5d [opt [arg value]
0650: 5d 20 5b 6f 70 74 20 5b 61 72 67 20 22 2d 6f 70 ] [opt [arg "-op
0660: 74 69 6f 6e 20 76 61 6c 75 65 20 2e 2e 2e 22 5d tion value ..."]
0670: 5d 5d 0a 0a 4f 70 74 69 6f 6e 61 6c 20 66 75 6e ]]..Optional fun
0680: 63 74 69 6f 6e 20 74 6f 20 73 65 74 20 74 68 65 ction to set the
0690: 20 64 65 66 61 75 6c 74 20 6f 70 74 69 6f 6e 73 default options
06a0: 20 75 73 65 64 20 62 79 20 5b 63 6d 64 20 74 6c used by [cmd tl
06b0: 73 3a 3a 73 6f 63 6b 65 74 5d 2e 20 49 66 20 79 s::socket]. If y
06c0: 6f 75 0a 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 ou.call [cmd tls
06d0: 3a 3a 69 6d 70 6f 72 74 5d 20 64 69 72 65 63 74 ::import] direct
06e0: 6c 79 2c 20 74 68 69 73 20 63 6f 6d 6d 61 6e 64 ly, this command
06f0: 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 2e 20 has no effect.
0700: 54 68 69 73 20 63 6f 6d 6d 61 6e 64 0a 73 75 70 This command.sup
0710: 70 6f 72 74 73 20 61 6c 6c 20 6f 66 20 74 68 65 ports all of the
0720: 20 73 61 6d 65 20 6f 70 74 69 6f 6e 73 20 61 73 same options as
0730: 20 74 68 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 73 the [cmd tls::s
0740: 6f 63 6b 65 74 5d 20 63 6f 6d 6d 61 6e 64 2c 20 ocket] command,
0750: 74 68 6f 75 67 68 20 79 6f 75 0a 73 68 6f 75 6c though you.shoul
0760: 64 20 6c 69 6d 69 74 20 79 6f 75 72 20 6f 70 74 d limit your opt
0770: 69 6f 6e 73 20 74 6f 20 6f 6e 6c 79 20 54 4c 53 ions to only TLS
0780: 20 72 65 6c 61 74 65 64 20 6f 6e 65 73 2e 0a 0a related ones...
0790: 5b 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a [call [cmd tls::
07a0: 73 6f 63 6b 65 74 5d 20 5b 6f 70 74 20 5b 61 72 socket] [opt [ar
07b0: 67 20 2d 6f 70 74 69 6f 6e 5d 5d 20 5b 6f 70 74 g -option]] [opt
07c0: 20 5b 61 72 67 20 76 61 6c 75 65 5d 5d 20 5b 6f [arg value]] [o
07d0: 70 74 20 5b 61 72 67 20 22 2d 6f 70 74 69 6f 6e pt [arg "-option
07e0: 20 76 61 6c 75 65 20 2e 2e 2e 22 5d 5d 20 5b 61 value ..."]] [a
07f0: 72 67 20 68 6f 73 74 5d 20 5b 61 72 67 20 70 6f rg host] [arg po
0800: 72 74 5d 5d 0a 0a 54 68 69 73 20 69 73 20 61 20 rt]]..This is a
0810: 68 65 6c 70 65 72 20 66 75 6e 63 74 69 6f 6e 20 helper function
0820: 74 68 61 74 20 75 74 69 6c 69 7a 65 73 20 74 68 that utilizes th
0830: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 6f 6d e underlying com
0840: 6d 61 6e 64 73 20 5b 73 79 73 63 6d 64 20 73 6f mands [syscmd so
0850: 63 6b 65 74 5d 0a 61 6e 64 20 5b 63 6d 64 20 74 cket].and [cmd t
0860: 6c 73 3a 3a 69 6d 70 6f 72 74 5d 20 74 6f 20 63 ls::import] to c
0870: 72 65 61 74 65 20 74 68 65 20 63 6f 6e 6e 65 63 reate the connec
0880: 74 69 6f 6e 2e 20 49 74 20 62 65 68 61 76 65 73 tion. It behaves
0890: 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 the same as the
08a0: 0a 6e 61 74 69 76 65 20 54 43 4c 20 5b 73 79 73 .native TCL [sys
08b0: 63 6d 64 20 73 6f 63 6b 65 74 5d 20 63 6f 6d 6d cmd socket] comm
08c0: 61 6e 64 2c 20 62 75 74 20 61 6c 73 6f 20 73 75 and, but also su
08d0: 70 70 6f 72 74 73 20 74 68 65 20 5b 63 6d 64 20 pports the [cmd
08e0: 74 6c 73 3a 69 6d 70 6f 72 74 5d 0a 63 6f 6d 6d tls:import].comm
08f0: 61 6e 64 20 6f 70 74 69 6f 6e 73 20 77 69 74 68 and options with
0900: 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 one additional
0910: 6f 70 74 69 6f 6e 2e 20 49 74 20 72 65 74 75 72 option. It retur
0920: 6e 73 20 74 68 65 20 63 68 61 6e 6e 65 6c 20 68 ns the channel h
0930: 61 6e 64 6c 65 20 69 64 0a 66 6f 72 20 74 68 65 andle id.for the
0940: 20 6e 65 77 20 73 6f 63 6b 65 74 2e 0a 0a 5b 6c new socket...[l
0950: 69 73 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f 6e ist_begin option
0960: 73 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 61 75 s]..[opt_def -au
0970: 74 6f 73 65 72 76 65 72 6e 61 6d 65 20 5b 61 72 toservername [ar
0980: 67 20 62 6f 6f 6c 5d 5d 0a 49 66 20 5b 63 6f 6e g bool]].If [con
0990: 73 74 20 74 72 75 65 5d 2c 20 61 75 74 6f 6d 61 st true], automa
09a0: 74 69 63 61 6c 6c 79 20 73 65 74 20 74 68 65 20 tically set the
09b0: 5b 6f 70 74 69 6f 6e 20 2d 73 65 72 76 65 72 6e [option -servern
09c0: 61 6d 65 5d 20 61 72 67 75 6d 65 6e 74 20 74 6f ame] argument to
09d0: 20 74 68 65 0a 5b 65 6d 70 68 20 68 6f 73 74 5d the.[emph host]
09e0: 20 61 72 67 75 6d 65 6e 74 2e 20 50 72 69 6f 72 argument. Prior
09f0: 20 74 6f 20 54 63 6c 54 4c 53 20 32 2e 30 2c 20 to TclTLS 2.0,
0a00: 74 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 5b the default is [
0a10: 63 6f 6e 73 74 20 66 61 6c 73 65 5d 2e 0a 53 74 const false]..St
0a20: 61 72 74 69 6e 67 20 69 6e 20 54 63 6c 54 4c 53 arting in TclTLS
0a30: 20 32 2e 30 2c 20 74 68 65 20 64 65 66 61 75 6c 2.0, the defaul
0a40: 74 20 69 73 20 5b 63 6f 6e 73 74 20 74 72 75 65 t is [const true
0a50: 5d 20 75 6e 6c 65 73 73 20 5b 6f 70 74 69 6f 6e ] unless [option
0a60: 20 2d 73 65 72 76 65 72 6e 61 6d 65 5d 0a 69 73 -servername].is
0a70: 20 61 6c 73 6f 20 73 70 65 63 69 66 69 65 64 2e also specified.
0a80: 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 63 ..[list_end]..[c
0a90: 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 3a 3a 73 6f all [cmd tls::so
0aa0: 63 6b 65 74 5d 20 5b 6f 70 74 69 6f 6e 20 2d 73 cket] [option -s
0ab0: 65 72 76 65 72 5d 20 5b 61 72 67 20 63 6f 6d 6d erver] [arg comm
0ac0: 61 6e 64 5d 20 5b 6f 70 74 20 5b 61 72 67 20 2d and] [opt [arg -
0ad0: 6f 70 74 69 6f 6e 5d 5d 20 5b 6f 70 74 20 5b 61 option]] [opt [a
0ae0: 72 67 20 76 61 6c 75 65 5d 5d 20 5b 6f 70 74 20 rg value]] [opt
0af0: 5b 61 72 67 20 22 2d 6f 70 74 69 6f 6e 20 76 61 [arg "-option va
0b00: 6c 75 65 20 2e 2e 2e 22 5d 5d 20 5b 61 72 67 20 lue ..."]] [arg
0b10: 70 6f 72 74 5d 5d 0a 0a 53 61 6d 65 20 61 73 20 port]]..Same as
0b20: 70 72 65 76 69 6f 75 73 2c 20 62 75 74 20 69 6e previous, but in
0b30: 73 74 65 61 64 20 63 72 65 61 74 65 73 20 61 20 stead creates a
0b40: 73 65 72 76 65 72 20 73 6f 63 6b 65 74 20 66 6f server socket fo
0b50: 72 20 63 6c 69 65 6e 74 73 20 74 6f 20 63 6f 6e r clients to con
0b60: 6e 65 63 74 20 74 6f 0a 6a 75 73 74 20 6c 69 6b nect to.just lik
0b70: 65 20 74 68 65 20 54 63 6c 20 5b 73 79 73 63 6d e the Tcl [syscm
0b80: 64 20 22 73 6f 63 6b 65 74 20 2d 73 65 72 76 65 d "socket -serve
0b90: 72 22 5d 20 63 6f 6d 6d 61 6e 64 2e 20 49 74 20 r"] command. It
0ba0: 72 65 74 75 72 6e 73 20 74 68 65 20 63 68 61 6e returns the chan
0bb0: 6e 65 6c 0a 68 61 6e 64 6c 65 20 69 64 20 66 6f nel.handle id fo
0bc0: 72 20 74 68 65 20 6e 65 77 20 73 6f 63 6b 65 74 r the new socket
0bd0: 2e 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 74 6c ...[call [cmd tl
0be0: 73 3a 3a 69 6d 70 6f 72 74 5d 20 5b 61 72 67 20 s::import] [arg
0bf0: 63 68 61 6e 6e 65 6c 5d 20 5b 6f 70 74 20 5b 61 channel] [opt [a
0c00: 72 67 20 2d 6f 70 74 69 6f 6e 5d 5d 20 5b 6f 70 rg -option]] [op
0c10: 74 20 5b 61 72 67 20 76 61 6c 75 65 5d 5d 20 5b t [arg value]] [
0c20: 6f 70 74 20 5b 61 72 67 20 22 2d 6f 70 74 69 6f opt [arg "-optio
0c30: 6e 20 76 61 6c 75 65 20 2e 2e 2e 22 5d 5d 5d 0a n value ..."]]].
0c40: 0a 53 74 61 72 74 20 54 4c 53 20 65 6e 63 72 79 .Start TLS encry
0c50: 70 74 69 6f 6e 20 6f 6e 20 54 43 4c 20 63 68 61 ption on TCL cha
0c60: 6e 6e 65 6c 20 5b 61 72 67 20 63 68 61 6e 6e 65 nnel [arg channe
0c70: 6c 5d 20 76 69 61 20 61 20 73 74 61 63 6b 65 64 l] via a stacked
0c80: 20 63 68 61 6e 6e 65 6c 2e 20 49 74 0a 6e 65 65 channel. It.nee
0c90: 64 20 6e 6f 74 20 62 65 20 61 20 73 6f 63 6b 65 d not be a socke
0ca0: 74 2c 20 62 75 74 20 6d 75 73 74 20 70 72 6f 76 t, but must prov
0cb0: 69 64 65 20 62 69 2d 64 69 72 65 63 74 69 6f 6e ide bi-direction
0cc0: 61 6c 20 66 6c 6f 77 2e 20 41 6c 73 6f 20 73 65 al flow. Also se
0cd0: 74 73 20 73 65 73 73 69 6f 6e 0a 70 61 72 61 6d ts session.param
0ce0: 65 74 65 72 73 20 66 6f 72 20 53 53 4c 20 68 61 eters for SSL ha
0cf0: 6e 64 73 68 61 6b 65 2e 20 56 61 6c 69 64 20 6f ndshake. Valid o
0d00: 70 74 69 6f 6e 73 20 61 72 65 3a 0a 0a 5b 6c 69 ptions are:..[li
0d10: 73 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f 6e 73 st_begin options
0d20: 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 61 6c 70 ]..[opt_def -alp
0d30: 6e 20 5b 61 72 67 20 6c 69 73 74 5d 5d 0a 4c 69 n [arg list]].Li
0d40: 73 74 20 6f 66 20 70 72 6f 74 6f 63 6f 6c 73 20 st of protocols
0d50: 74 6f 20 6f 66 66 65 72 20 64 75 72 69 6e 67 20 to offer during
0d60: 41 70 70 6c 69 63 61 74 69 6f 6e 2d 4c 61 79 65 Application-Laye
0d70: 72 20 50 72 6f 74 6f 63 6f 6c 20 4e 65 67 6f 74 r Protocol Negot
0d80: 69 61 74 69 6f 6e 0a 28 41 4c 50 4e 29 2e 20 46 iation.(ALPN). F
0d90: 6f 72 20 65 78 61 6d 70 6c 65 3a 20 5b 63 6f 6e or example: [con
0da0: 73 74 20 68 32 5d 20 61 6e 64 20 5b 63 6f 6e 73 st h2] and [cons
0db0: 74 20 68 74 74 70 2f 31 2e 31 5d 2c 20 62 75 74 t http/1.1], but
0dc0: 20 6e 6f 74 20 5b 63 6f 6e 73 74 20 68 33 5d 20 not [const h3]
0dd0: 6f 72 0a 5b 63 6f 6e 73 74 20 71 75 69 63 5d 2e or.[const quic].
0de0: 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 61 64 69 ..[opt_def -cadi
0df0: 72 20 5b 61 72 67 20 64 69 72 65 63 74 6f 72 79 r [arg directory
0e00: 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 ]].Specifies the
0e10: 20 64 69 72 65 63 74 6f 72 79 20 77 68 65 72 65 directory where
0e20: 20 74 68 65 20 43 65 72 74 69 66 69 63 61 74 65 the Certificate
0e30: 20 41 75 74 68 6f 72 69 74 79 20 28 43 41 29 20 Authority (CA)
0e40: 63 65 72 74 69 66 69 63 61 74 65 73 20 61 72 65 certificates are
0e50: 0a 73 74 6f 72 65 64 2e 20 54 68 65 20 64 65 66 .stored. The def
0e60: 61 75 6c 74 20 69 73 20 70 6c 61 74 66 6f 72 6d ault is platform
0e70: 20 73 70 65 63 69 66 69 63 20 61 6e 64 20 63 61 specific and ca
0e80: 6e 20 62 65 20 73 65 74 20 61 74 20 63 6f 6d 70 n be set at comp
0e90: 69 6c 65 20 74 69 6d 65 2e 20 54 68 65 0a 64 65 ile time. The.de
0ea0: 66 61 75 6c 74 20 6c 6f 63 61 74 69 6f 6e 20 63 fault location c
0eb0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
0ec0: 20 62 79 20 74 68 65 20 5b 76 61 72 20 53 53 4c by the [var SSL
0ed0: 5f 43 45 52 54 5f 44 49 52 5d 20 65 6e 76 69 72 _CERT_DIR] envir
0ee0: 6f 6e 6d 65 6e 74 0a 76 61 72 69 61 62 6c 65 2e onment.variable.
0ef0: 20 53 65 65 20 5b 73 65 63 74 72 65 66 20 22 43 See [sectref "C
0f00: 65 72 74 69 66 69 63 61 74 65 20 56 61 6c 69 64 ertificate Valid
0f10: 61 74 69 6f 6e 22 5d 20 66 6f 72 20 6d 6f 72 65 ation"] for more
0f20: 20 64 65 74 61 69 6c 73 2e 0a 0a 5b 6f 70 74 5f details...[opt_
0f30: 64 65 66 20 2d 63 61 66 69 6c 65 20 5b 61 72 67 def -cafile [arg
0f40: 20 66 69 6c 65 6e 61 6d 65 5d 5d 0a 53 70 65 63 filename]].Spec
0f50: 69 66 69 65 73 20 74 68 65 20 66 69 6c 65 20 77 ifies the file w
0f60: 69 74 68 20 74 68 65 20 43 65 72 74 69 66 69 63 ith the Certific
0f70: 61 74 65 20 41 75 74 68 6f 72 69 74 79 20 28 43 ate Authority (C
0f80: 41 29 20 63 65 72 74 69 66 69 63 61 74 65 73 20 A) certificates
0f90: 74 6f 20 75 73 65 20 69 6e 0a 5b 63 6f 6e 73 74 to use in.[const
0fa0: 20 50 45 4d 5d 20 66 69 6c 65 20 66 6f 72 6d 61 PEM] file forma
0fb0: 74 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 t. The default i
0fc0: 73 20 5b 66 69 6c 65 20 63 65 72 74 2e 70 65 6d s [file cert.pem
0fd0: 5d 2c 20 69 6e 20 74 68 65 20 4f 70 65 6e 53 53 ], in the OpenSS
0fe0: 4c 0a 64 69 72 65 63 74 6f 72 79 2e 20 54 68 65 L.directory. The
0ff0: 20 64 65 66 61 75 6c 74 20 66 69 6c 65 20 63 61 default file ca
1000: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 n be overridden
1010: 62 79 20 74 68 65 20 5b 76 61 72 20 53 53 4c 5f by the [var SSL_
1020: 43 45 52 54 5f 46 49 4c 45 5d 20 65 6e 76 69 72 CERT_FILE] envir
1030: 6f 6e 6d 65 6e 74 0a 76 61 72 69 61 62 6c 65 2e onment.variable.
1040: 20 53 65 65 20 5b 73 65 63 74 72 65 66 20 22 43 See [sectref "C
1050: 65 72 74 69 66 69 63 61 74 65 20 56 61 6c 69 64 ertificate Valid
1060: 61 74 69 6f 6e 22 5d 20 66 6f 72 20 6d 6f 72 65 ation"] for more
1070: 20 64 65 74 61 69 6c 73 2e 0a 0a 5b 6f 70 74 5f details...[opt_
1080: 64 65 66 20 2d 63 61 73 74 6f 72 65 20 5b 61 72 def -castore [ar
1090: 67 20 55 52 49 5d 5d 0a 53 70 65 63 69 66 69 65 g URI]].Specifie
10a0: 73 20 74 68 65 20 55 6e 69 66 6f 72 6d 20 52 65 s the Uniform Re
10b0: 73 6f 75 72 63 65 20 49 64 65 6e 74 69 66 69 65 source Identifie
10c0: 72 20 28 55 52 49 29 20 66 6f 72 20 74 68 65 20 r (URI) for the
10d0: 43 65 72 74 69 66 69 63 61 74 65 20 41 75 74 68 Certificate Auth
10e0: 6f 72 69 74 79 0a 28 43 41 29 20 73 74 6f 72 65 ority.(CA) store
10f0: 2c 20 77 68 69 63 68 20 6d 61 79 20 62 65 20 61 , which may be a
1100: 20 73 69 6e 67 6c 65 20 63 6f 6e 74 61 69 6e 65 single containe
1110: 72 20 6f 72 20 61 20 63 61 74 61 6c 6f 67 20 6f r or a catalog o
1120: 66 20 63 6f 6e 74 61 69 6e 65 72 73 2e 0a 53 74 f containers..St
1130: 61 72 74 69 6e 67 20 77 69 74 68 20 4f 70 65 6e arting with Open
1140: 53 53 4c 20 33 2e 32 20 6f 6e 20 4d 53 20 57 69 SSL 3.2 on MS Wi
1150: 6e 64 6f 77 73 2c 20 73 65 74 20 74 6f 20 22 5b ndows, set to "[
1160: 63 6f 6e 73 74 20 22 6f 72 67 2e 6f 70 65 6e 73 const "org.opens
1170: 73 6c 2e 77 69 6e 73 74 6f 72 65 3a 2f 2f 22 5d sl.winstore://"]
1180: 22 0a 74 6f 20 75 73 65 20 74 68 65 20 62 75 69 ".to use the bui
1190: 6c 74 2d 69 6e 20 4d 53 20 57 69 6e 64 6f 77 73 lt-in MS Windows
11a0: 20 43 65 72 74 69 66 69 63 61 74 65 20 53 74 6f Certificate Sto
11b0: 72 65 2e 20 53 65 65 0a 5b 73 65 63 74 72 65 66 re. See.[sectref
11c0: 20 22 43 65 72 74 69 66 69 63 61 74 65 20 56 61 "Certificate Va
11d0: 6c 69 64 61 74 69 6f 6e 22 5d 20 66 6f 72 20 6d lidation"] for m
11e0: 6f 72 65 20 64 65 74 61 69 6c 73 2e 0a 0a 5b 6f ore details...[o
11f0: 70 74 5f 64 65 66 20 2d 63 65 72 74 66 69 6c 65 pt_def -certfile
1200: 20 5b 61 72 67 20 66 69 6c 65 6e 61 6d 65 5d 5d [arg filename]]
1210: 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 20 6e .Specifies the n
1220: 61 6d 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ame of the file
1230: 77 69 74 68 20 74 68 65 20 63 65 72 74 69 66 69 with the certifi
1240: 63 61 74 65 20 74 6f 20 75 73 65 20 69 6e 20 50 cate to use in P
1250: 45 4d 20 66 6f 72 6d 61 74 0a 61 73 20 74 68 65 EM format.as the
1260: 20 6c 6f 63 61 6c 20 28 63 6c 69 65 6e 74 20 6f local (client o
1270: 72 20 73 65 72 76 65 72 29 20 63 65 72 74 69 66 r server) certif
1280: 69 63 61 74 65 2e 20 49 74 20 61 6c 73 6f 20 63 icate. It also c
1290: 6f 6e 74 61 69 6e 73 20 74 68 65 20 70 75 62 6c ontains the publ
12a0: 69 63 20 6b 65 79 2e 0a 0a 5b 6f 70 74 5f 64 65 ic key...[opt_de
12b0: 66 20 2d 63 65 72 74 20 5b 61 72 67 20 73 74 72 f -cert [arg str
12c0: 69 6e 67 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 ing]].Specifies
12d0: 74 68 65 20 63 65 72 74 69 66 69 63 61 74 65 20 the certificate
12e0: 74 6f 20 75 73 65 20 61 73 20 61 20 44 45 52 20 to use as a DER
12f0: 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 20 28 encoded string (
1300: 58 2e 35 30 39 20 44 45 52 29 2e 0a 0a 5b 6f 70 X.509 DER)...[op
1310: 74 5f 64 65 66 20 2d 63 69 70 68 65 72 20 5b 61 t_def -cipher [a
1320: 72 67 20 73 74 72 69 6e 67 5d 5d 0a 53 70 65 63 rg string]].Spec
1330: 69 66 69 65 73 20 74 68 65 20 6c 69 73 74 20 6f ifies the list o
1340: 66 20 63 69 70 68 65 72 73 20 74 6f 20 75 73 65 f ciphers to use
1350: 20 66 6f 72 20 54 4c 53 20 31 2e 32 20 61 6e 64 for TLS 1.2 and
1360: 20 65 61 72 6c 69 65 72 20 63 6f 6e 6e 65 63 74 earlier connect
1370: 69 6f 6e 73 2e 0a 53 74 72 69 6e 67 20 69 73 20 ions..String is
1380: 61 20 63 6f 6c 6f 6e 20 22 5b 63 6f 6e 73 74 20 a colon "[const
1390: 3a 5d 22 20 73 65 70 61 72 61 74 65 64 20 6c 69 :]" separated li
13a0: 73 74 20 6f 66 20 63 69 70 68 65 72 73 2e 0a 43 st of ciphers..C
13b0: 69 70 68 65 72 73 20 63 61 6e 20 62 65 20 63 6f iphers can be co
13c0: 6d 62 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 mbined using the
13d0: 20 22 5b 63 6f 6e 73 74 20 2b 5d 22 20 63 68 61 "[const +]" cha
13e0: 72 61 63 74 65 72 2e 0a 50 72 65 66 69 78 65 73 racter..Prefixes
13f0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1400: 70 65 72 6d 61 6e 65 6e 74 6c 79 20 72 65 6d 6f permanently remo
1410: 76 65 20 22 5b 63 6f 6e 73 74 20 21 5d 22 2c 20 ve "[const !]",
1420: 64 65 6c 65 74 65 20 22 5b 63 6f 6e 73 74 20 2d delete "[const -
1430: 5d 22 2c 20 6f 72 0a 6d 6f 76 65 20 74 6f 20 74 ]", or.move to t
1440: 68 65 20 65 6e 64 20 22 5b 63 6f 6e 73 74 20 2b he end "[const +
1450: 5d 22 20 61 20 73 70 65 63 69 66 69 65 64 20 63 ]" a specified c
1460: 69 70 68 65 72 2e 0a 4b 65 79 77 6f 72 64 73 20 ipher..Keywords
1470: 5b 63 6f 6e 73 74 20 40 53 54 52 45 4e 47 54 48 [const @STRENGTH
1480: 5d 20 28 73 6f 72 74 20 62 79 20 61 6c 67 6f 72 ] (sort by algor
1490: 69 74 68 6d 20 6b 65 79 20 6c 65 6e 67 74 68 29 ithm key length)
14a0: 2c 0a 5b 63 6f 6e 73 74 20 40 53 45 43 4c 45 56 ,.[const @SECLEV
14b0: 45 4c 3d 5d 5b 65 6d 70 68 20 6e 5d 20 28 73 65 EL=][emph n] (se
14c0: 74 20 73 65 63 75 72 69 74 79 20 6c 65 76 65 6c t security level
14d0: 20 74 6f 20 6e 29 2c 20 61 6e 64 0a 5b 63 6f 6e to n), and.[con
14e0: 73 74 20 44 45 46 41 55 4c 54 5d 20 28 75 73 65 st DEFAULT] (use
14f0: 20 64 65 66 61 75 6c 74 20 63 69 70 68 65 72 20 default cipher
1500: 6c 69 73 74 2c 20 61 74 20 73 74 61 72 74 20 6f list, at start o
1510: 6e 6c 79 29 20 63 61 6e 20 61 6c 73 6f 20 62 65 nly) can also be
1520: 20 73 70 65 63 69 66 69 65 64 2e 0a 53 65 65 20 specified..See
1530: 74 68 65 20 5b 75 72 69 20 22 68 74 74 70 73 3a the [uri "https:
1540: 2f 2f 64 6f 63 73 2e 6f 70 65 6e 73 73 6c 2e 6f //docs.openssl.o
1550: 72 67 2f 6d 61 73 74 65 72 2f 6d 61 6e 31 2f 6f rg/master/man1/o
1560: 70 65 6e 73 73 6c 2d 63 69 70 68 65 72 73 2f 23 penssl-ciphers/#
1570: 6f 70 74 69 6f 6e 73 22 20 4f 70 65 6e 53 53 4c options" OpenSSL
1580: 5d 0a 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ].documentation
1590: 66 6f 72 20 74 68 65 20 66 75 6c 6c 20 6c 69 73 for the full lis
15a0: 74 20 6f 66 20 76 61 6c 69 64 20 76 61 6c 75 65 t of valid value
15b0: 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 69 s...[opt_def -ci
15c0: 70 68 65 72 73 75 69 74 65 73 20 5b 61 72 67 20 phersuites [arg
15d0: 73 74 72 69 6e 67 5d 5d 0a 53 70 65 63 69 66 69 string]].Specifi
15e0: 65 73 20 74 68 65 20 6c 69 73 74 20 6f 66 20 63 es the list of c
15f0: 69 70 68 65 72 20 73 75 69 74 65 73 20 74 6f 20 ipher suites to
1600: 75 73 65 20 66 6f 72 20 54 4c 53 20 31 2e 33 20 use for TLS 1.3
1610: 61 73 20 61 20 63 6f 6c 6f 6e 0a 22 5b 63 6f 6e as a colon."[con
1620: 73 74 20 3a 5d 22 20 73 65 70 61 72 61 74 65 64 st :]" separated
1630: 20 6c 69 73 74 20 6f 66 20 63 69 70 68 65 72 20 list of cipher
1640: 73 75 69 74 65 20 6e 61 6d 65 73 2e 20 53 65 65 suite names. See
1650: 20 74 68 65 0a 5b 75 72 69 20 22 68 74 74 70 73 the.[uri "https
1660: 3a 2f 2f 64 6f 63 73 2e 6f 70 65 6e 73 73 6c 2e ://docs.openssl.
1670: 6f 72 67 2f 6d 61 73 74 65 72 2f 6d 61 6e 31 2f org/master/man1/
1680: 6f 70 65 6e 73 73 6c 2d 63 69 70 68 65 72 73 2f openssl-ciphers/
1690: 23 6f 70 74 69 6f 6e 73 22 20 4f 70 65 6e 53 53 #options" OpenSS
16a0: 4c 5d 0a 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e L].documentation
16b0: 20 66 6f 72 20 74 68 65 20 66 75 6c 6c 20 6c 69 for the full li
16c0: 73 74 20 6f 66 20 76 61 6c 69 64 20 76 61 6c 75 st of valid valu
16d0: 65 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 es...[opt_def -c
16e0: 6f 6d 6d 61 6e 64 20 5b 61 72 67 20 63 61 6c 6c ommand [arg call
16f0: 62 61 63 6b 5d 5d 0a 53 70 65 63 69 66 69 65 73 back]].Specifies
1700: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f the callback co
1710: 6d 6d 61 6e 64 20 74 6f 20 62 65 20 69 6e 76 6f mmand to be invo
1720: 6b 65 64 20 61 74 20 73 65 76 65 72 61 6c 20 70 ked at several p
1730: 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
1740: 0a 68 61 6e 64 73 68 61 6b 65 20 74 6f 20 70 61 .handshake to pa
1750: 73 73 20 65 72 72 6f 72 73 2c 20 74 72 61 63 69 ss errors, traci
1760: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 ng information,
1770: 61 6e 64 20 70 72 6f 74 6f 63 6f 6c 20 6d 65 73 and protocol mes
1780: 73 61 67 65 73 2e 0a 53 65 65 20 5b 73 65 63 74 sages..See [sect
1790: 72 65 66 20 22 43 61 6c 6c 62 61 63 6b 20 4f 70 ref "Callback Op
17a0: 74 69 6f 6e 73 22 5d 20 66 6f 72 20 6d 6f 72 65 tions"] for more
17b0: 20 69 6e 66 6f 2e 0a 0a 5b 6f 70 74 5f 64 65 66 info...[opt_def
17c0: 20 2d 64 68 70 61 72 61 6d 73 20 5b 61 72 67 20 -dhparams [arg
17d0: 66 69 6c 65 6e 61 6d 65 5d 5d 0a 53 70 65 63 69 filename]].Speci
17e0: 66 69 65 73 20 74 68 65 20 44 69 66 66 69 65 2d fies the Diffie-
17f0: 48 65 6c 6c 6d 61 6e 20 28 44 48 29 20 70 61 72 Hellman (DH) par
1800: 61 6d 65 74 65 72 73 20 66 69 6c 65 2e 0a 0a 5b ameters file...[
1810: 6f 70 74 5f 64 65 66 20 2d 6b 65 79 66 69 6c 65 opt_def -keyfile
1820: 20 5b 61 72 67 20 66 69 6c 65 6e 61 6d 65 5d 5d [arg filename]]
1830: 0a 53 70 65 63 69 66 69 65 73 20 74 68 65 20 70 .Specifies the p
1840: 72 69 76 61 74 65 20 6b 65 79 20 66 69 6c 65 2e rivate key file.
1850: 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 The default is
1860: 74 6f 20 75 73 65 20 74 68 65 20 66 69 6c 65 0a to use the file.
1870: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
1880: 20 5b 61 72 67 20 2d 63 65 72 74 66 69 6c 65 5d [arg -certfile]
1890: 20 6f 70 74 69 6f 6e 2e 0a 0a 5b 6f 70 74 5f 64 option...[opt_d
18a0: 65 66 20 2d 6b 65 79 20 5b 61 72 67 20 73 74 72 ef -key [arg str
18b0: 69 6e 67 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 ing]].Specifies
18c0: 74 68 65 20 70 72 69 76 61 74 65 20 6b 65 79 20 the private key
18d0: 74 6f 20 75 73 65 20 61 73 20 61 20 44 45 52 20 to use as a DER
18e0: 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 20 28 encoded string (
18f0: 50 4b 43 53 23 31 20 44 45 52 29 2e 0a 0a 5b 6f PKCS#1 DER)...[o
1900: 70 74 5f 64 65 66 20 2d 6d 6f 64 65 6c 20 5b 61 pt_def -model [a
1910: 72 67 20 63 68 61 6e 6e 65 6c 5d 5d 0a 46 6f 72 rg channel]].For
1920: 63 65 20 74 68 69 73 20 63 68 61 6e 6e 65 6c 20 ce this channel
1930: 74 6f 20 73 68 61 72 65 20 74 68 65 20 73 61 6d to share the sam
1940: 65 20 5b 74 65 72 6d 20 53 53 4c 5f 43 54 58 5d e [term SSL_CTX]
1950: 20 73 74 72 75 63 74 75 72 65 20 61 73 20 74 68 structure as th
1960: 65 0a 73 70 65 63 69 66 69 65 64 20 5b 61 72 67 e.specified [arg
1970: 20 63 68 61 6e 6e 65 6c 5d 2c 20 61 6e 64 20 74 channel], and t
1980: 68 65 72 65 66 6f 72 65 20 73 68 61 72 65 20 63 herefore share c
1990: 6f 6e 66 69 67 2c 20 63 61 6c 6c 62 61 63 6b 73 onfig, callbacks
19a0: 2c 20 65 74 63 2e 0a 0a 5b 6f 70 74 5f 64 65 66 , etc...[opt_def
19b0: 20 2d 70 61 73 73 77 6f 72 64 20 5b 61 72 67 20 -password [arg
19c0: 63 61 6c 6c 62 61 63 6b 5d 5d 0a 53 70 65 63 69 callback]].Speci
19d0: 66 69 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 fies the callbac
19e0: 6b 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 69 6e 76 k command to inv
19f0: 6f 6b 65 20 77 68 65 6e 20 4f 70 65 6e 53 53 4c oke when OpenSSL
1a00: 20 6e 65 65 64 73 20 74 6f 20 6f 62 74 61 69 6e needs to obtain
1a10: 20 61 0a 70 61 73 73 77 6f 72 64 2e 20 54 68 69 a.password. Thi
1a20: 73 20 69 73 20 74 79 70 69 63 61 6c 6c 79 20 75 s is typically u
1a30: 73 65 64 20 74 6f 20 75 6e 6c 6f 63 6b 20 74 68 sed to unlock th
1a40: 65 20 70 72 69 76 61 74 65 20 6b 65 79 20 6f 66 e private key of
1a50: 20 61 20 63 65 72 74 69 66 69 63 61 74 65 2e 0a a certificate..
1a60: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f The callback sho
1a70: 75 6c 64 20 72 65 74 75 72 6e 20 61 20 70 61 73 uld return a pas
1a80: 73 77 6f 72 64 20 73 74 72 69 6e 67 2e 20 53 65 sword string. Se
1a90: 65 20 5b 73 65 63 74 72 65 66 20 22 43 61 6c 6c e [sectref "Call
1aa0: 62 61 63 6b 20 4f 70 74 69 6f 6e 73 22 5d 0a 66 back Options"].f
1ab0: 6f 72 20 6d 6f 72 65 20 69 6e 66 6f 2e 0a 0a 5b or more info...[
1ac0: 6f 70 74 5f 64 65 66 20 2d 70 6f 73 74 5f 68 61 opt_def -post_ha
1ad0: 6e 64 73 68 61 6b 65 20 5b 61 72 67 20 62 6f 6f ndshake [arg boo
1ae0: 6c 5d 5d 0a 41 6c 6c 6f 77 20 70 6f 73 74 2d 68 l]].Allow post-h
1af0: 61 6e 64 73 68 61 6b 65 20 73 65 73 73 69 6f 6e andshake session
1b00: 20 74 69 63 6b 65 74 20 75 70 64 61 74 65 73 2e ticket updates.
1b10: 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 72 65 71 75 ..[opt_def -requ
1b20: 65 73 74 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a est [arg bool]].
1b30: 52 65 71 75 65 73 74 20 61 20 63 65 72 74 69 66 Request a certif
1b40: 69 63 61 74 65 20 66 72 6f 6d 20 74 68 65 20 70 icate from the p
1b50: 65 65 72 20 64 75 72 69 6e 67 20 74 68 65 20 53 eer during the S
1b60: 53 4c 20 68 61 6e 64 73 68 61 6b 65 2e 20 54 68 SL handshake. Th
1b70: 69 73 20 69 73 20 6e 65 65 64 65 64 0a 74 6f 20 is is needed.to
1b80: 64 6f 20 43 65 72 74 69 66 69 63 61 74 65 20 56 do Certificate V
1b90: 61 6c 69 64 61 74 69 6f 6e 2e 20 53 74 61 72 74 alidation. Start
1ba0: 69 6e 67 20 69 6e 20 54 63 6c 54 4c 53 20 31 2e ing in TclTLS 1.
1bb0: 38 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 69 8, the default i
1bc0: 73 0a 5b 63 6f 6e 73 74 20 74 72 75 65 5d 2e 20 s.[const true].
1bd0: 53 74 61 72 74 69 6e 67 20 69 6e 20 54 63 6c 54 Starting in TclT
1be0: 4c 53 20 32 2e 30 2c 20 49 66 20 73 65 74 20 74 LS 2.0, If set t
1bf0: 6f 20 5b 63 6f 6e 73 74 20 66 61 6c 73 65 5d 20 o [const false]
1c00: 61 6e 64 0a 5b 6f 70 74 69 6f 6e 20 2d 72 65 71 and.[option -req
1c10: 75 69 72 65 5d 20 69 73 20 5b 63 6f 6e 73 74 20 uire] is [const
1c20: 74 72 75 65 5d 2c 20 74 68 65 6e 20 74 68 69 73 true], then this
1c30: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 72 69 64 will be overrid
1c40: 64 65 6e 20 74 6f 20 5b 63 6f 6e 73 74 20 74 72 den to [const tr
1c50: 75 65 5d 2e 0a 53 65 65 20 5b 73 65 63 74 72 65 ue]..See [sectre
1c60: 66 20 22 43 65 72 74 69 66 69 63 61 74 65 20 56 f "Certificate V
1c70: 61 6c 69 64 61 74 69 6f 6e 22 5d 20 66 6f 72 20 alidation"] for
1c80: 6d 6f 72 65 20 64 65 74 61 69 6c 73 2e 0a 0a 5b more details...[
1c90: 6f 70 74 5f 64 65 66 20 2d 72 65 71 75 69 72 65 opt_def -require
1ca0: 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 52 65 71 [arg bool]].Req
1cb0: 75 69 72 65 20 61 20 76 61 6c 69 64 20 63 65 72 uire a valid cer
1cc0: 74 69 66 69 63 61 74 65 20 66 72 6f 6d 20 74 68 tificate from th
1cd0: 65 20 70 65 65 72 20 64 75 72 69 6e 67 20 74 68 e peer during th
1ce0: 65 20 53 53 4c 20 68 61 6e 64 73 68 61 6b 65 2e e SSL handshake.
1cf0: 20 49 66 20 74 68 69 73 20 69 73 0a 73 65 74 20 If this is.set
1d00: 74 6f 20 74 72 75 65 2c 20 74 68 65 6e 20 5b 6f to true, then [o
1d10: 70 74 69 6f 6e 20 2d 72 65 71 75 65 73 74 5d 20 ption -request]
1d20: 6d 75 73 74 20 61 6c 73 6f 20 62 65 20 73 65 74 must also be set
1d30: 20 74 6f 20 74 72 75 65 20 61 6e 64 20 61 20 65 to true and a e
1d40: 69 74 68 65 72 0a 5b 6f 70 74 69 6f 6e 20 2d 63 ither.[option -c
1d50: 61 64 69 72 5d 2c 20 5b 6f 70 74 69 6f 6e 20 2d adir], [option -
1d60: 63 61 66 69 6c 65 5d 2c 20 5b 6f 70 74 69 6f 6e cafile], [option
1d70: 20 2d 63 61 73 74 6f 72 65 5d 2c 20 6f 72 20 61 -castore], or a
1d80: 20 70 6c 61 74 66 6f 72 6d 20 64 65 66 61 75 6c platform defaul
1d90: 74 0a 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 t.must be provid
1da0: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 76 ed in order to v
1db0: 61 6c 69 64 61 74 65 20 61 67 61 69 6e 73 74 2e alidate against.
1dc0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6e 20 The default in
1dd0: 54 63 6c 54 4c 53 20 31 2e 38 20 61 6e 64 0a 65 TclTLS 1.8 and.e
1de0: 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 arlier versions
1df0: 69 73 20 5b 63 6f 6e 73 74 20 66 61 6c 73 65 5d is [const false]
1e00: 20 73 69 6e 63 65 20 6e 6f 74 20 61 6c 6c 20 70 since not all p
1e10: 6c 61 74 66 6f 72 6d 73 20 68 61 76 65 20 63 65 latforms have ce
1e20: 72 74 69 66 69 63 61 74 65 73 20 74 6f 0a 76 61 rtificates to.va
1e30: 6c 69 64 61 74 65 20 61 67 61 69 6e 73 74 20 69 lidate against i
1e40: 6e 20 61 20 66 6f 72 6d 20 63 6f 6d 70 61 74 69 n a form compati
1e50: 62 6c 65 20 77 69 74 68 20 4f 70 65 6e 53 53 4c ble with OpenSSL
1e60: 2e 20 53 74 61 72 74 69 6e 67 20 69 6e 20 54 63 . Starting in Tc
1e70: 6c 54 4c 53 20 32 2e 30 2c 0a 74 68 65 20 64 65 lTLS 2.0,.the de
1e80: 66 61 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 fault is [const
1e90: 74 72 75 65 5d 2e 0a 53 65 65 20 5b 73 65 63 74 true]..See [sect
1ea0: 72 65 66 20 22 43 65 72 74 69 66 69 63 61 74 65 ref "Certificate
1eb0: 20 56 61 6c 69 64 61 74 69 6f 6e 22 5d 20 66 6f Validation"] fo
1ec0: 72 20 6d 6f 72 65 20 64 65 74 61 69 6c 73 2e 0a r more details..
1ed0: 0a 5b 6f 70 74 5f 64 65 66 20 2d 73 65 63 75 72 .[opt_def -secur
1ee0: 69 74 79 5f 6c 65 76 65 6c 20 5b 61 72 67 20 69 ity_level [arg i
1ef0: 6e 74 65 67 65 72 5d 5d 0a 53 70 65 63 69 66 69 nteger]].Specifi
1f00: 65 73 20 74 68 65 20 73 65 63 75 72 69 74 79 20 es the security
1f10: 6c 65 76 65 6c 20 28 76 61 6c 75 65 20 66 72 6f level (value fro
1f20: 6d 20 30 20 74 6f 20 35 29 2e 20 54 68 65 20 73 m 0 to 5). The s
1f30: 65 63 75 72 69 74 79 20 6c 65 76 65 6c 20 61 66 ecurity level af
1f40: 66 65 63 74 73 0a 74 68 65 20 61 6c 6c 6f 77 65 fects.the allowe
1f50: 64 20 63 69 70 68 65 72 20 73 75 69 74 65 20 65 d cipher suite e
1f60: 6e 63 72 79 70 74 69 6f 6e 20 61 6c 67 6f 72 69 ncryption algori
1f70: 74 68 6d 73 2c 20 73 75 70 70 6f 72 74 65 64 20 thms, supported
1f80: 45 43 43 20 63 75 72 76 65 73 2c 0a 73 75 70 70 ECC curves,.supp
1f90: 6f 72 74 65 64 20 73 69 67 6e 61 74 75 72 65 20 orted signature
1fa0: 61 6c 67 6f 72 69 74 68 6d 73 2c 20 44 48 20 70 algorithms, DH p
1fb0: 61 72 61 6d 65 74 65 72 20 73 69 7a 65 73 2c 20 arameter sizes,
1fc0: 63 65 72 74 69 66 69 63 61 74 65 20 6b 65 79 20 certificate key
1fd0: 73 69 7a 65 73 0a 61 6e 64 20 73 69 67 6e 61 74 sizes.and signat
1fe0: 75 72 65 20 61 6c 67 6f 72 69 74 68 6d 73 2e 20 ure algorithms.
1ff0: 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 31 The default is 1
2000: 20 70 72 69 6f 72 20 74 6f 20 4f 70 65 6e 53 53 prior to OpenSS
2010: 4c 20 33 2e 32 20 61 6e 64 20 32 0a 74 68 65 72 L 3.2 and 2.ther
2020: 65 61 66 74 65 72 2e 20 4c 65 76 65 6c 20 33 20 eafter. Level 3
2030: 61 6e 64 20 68 69 67 68 65 72 20 64 69 73 61 62 and higher disab
2040: 6c 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 73 le support for s
2050: 65 73 73 69 6f 6e 20 74 69 63 6b 65 74 73 20 61 ession tickets a
2060: 6e 64 0a 6f 6e 6c 79 20 61 63 63 65 70 74 20 63 nd.only accept c
2070: 69 70 68 65 72 20 73 75 69 74 65 73 20 74 68 61 ipher suites tha
2080: 74 20 70 72 6f 76 69 64 65 20 66 6f 72 77 61 72 t provide forwar
2090: 64 20 73 65 63 72 65 63 79 2e 0a 0a 5b 6f 70 74 d secrecy...[opt
20a0: 5f 64 65 66 20 2d 73 65 72 76 65 72 20 5b 61 72 _def -server [ar
20b0: 67 20 62 6f 6f 6c 5d 5d 0a 53 70 65 63 69 66 69 g bool]].Specifi
20c0: 65 73 20 77 68 65 74 68 65 72 20 74 6f 20 61 63 es whether to ac
20d0: 74 20 61 73 20 61 20 73 65 72 76 65 72 20 61 6e t as a server an
20e0: 64 20 72 65 73 70 6f 6e 64 20 77 69 74 68 20 61 d respond with a
20f0: 20 73 65 72 76 65 72 20 68 61 6e 64 73 68 61 6b server handshak
2100: 65 20 77 68 65 6e 20 61 0a 63 6c 69 65 6e 74 20 e when a.client
2110: 63 6f 6e 6e 65 63 74 73 20 61 6e 64 20 70 72 6f connects and pro
2120: 76 69 64 65 73 20 61 20 63 6c 69 65 6e 74 20 68 vides a client h
2130: 61 6e 64 73 68 61 6b 65 2e 20 54 68 65 20 64 65 andshake. The de
2140: 66 61 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 fault is [const
2150: 66 61 6c 73 65 5d 2e 0a 0a 5b 6f 70 74 5f 64 65 false]...[opt_de
2160: 66 20 2d 73 65 72 76 65 72 6e 61 6d 65 20 5b 61 f -servername [a
2170: 72 67 20 68 6f 73 74 6e 61 6d 65 5d 5d 0a 53 70 rg hostname]].Sp
2180: 65 63 69 66 79 20 74 68 65 20 70 65 65 72 27 73 ecify the peer's
2190: 20 68 6f 73 74 6e 61 6d 65 2e 20 54 68 69 73 20 hostname. This
21a0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 74 is used to set t
21b0: 68 65 20 54 4c 53 20 53 65 72 76 65 72 20 4e 61 he TLS Server Na
21c0: 6d 65 20 49 6e 64 69 63 61 74 69 6f 6e 0a 28 53 me Indication.(S
21d0: 4e 49 29 20 65 78 74 65 6e 73 69 6f 6e 2e 20 53 NI) extension. S
21e0: 65 74 20 74 68 69 73 20 74 6f 20 74 68 65 20 65 et this to the e
21f0: 78 70 65 63 74 65 64 20 73 65 72 76 65 72 6e 61 xpected serverna
2200: 6d 65 20 69 6e 20 74 68 65 20 73 65 72 76 65 72 me in the server
2210: 27 73 20 63 65 72 74 69 66 69 63 61 74 65 0a 6f 's certificate.o
2220: 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 53 75 62 r one of the Sub
2230: 6a 65 63 74 20 41 6c 74 65 72 6e 61 74 65 20 4e ject Alternate N
2240: 61 6d 65 73 20 28 53 41 4e 29 2e 20 53 74 61 72 ames (SAN). Star
2250: 74 69 6e 67 20 69 6e 20 54 63 6c 54 4c 53 20 32 ting in TclTLS 2
2260: 2e 30 2c 20 74 68 69 73 20 77 69 6c 6c 0a 64 65 .0, this will.de
2270: 66 61 75 6c 74 20 74 6f 20 74 68 65 20 68 6f 73 fault to the hos
2280: 74 20 66 6f 72 20 74 68 65 20 5b 63 6d 64 20 74 t for the [cmd t
2290: 6c 73 3a 3a 73 6f 63 6b 65 74 5d 20 63 6f 6d 6d ls::socket] comm
22a0: 61 6e 64 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d and...[opt_def -
22b0: 73 65 73 73 69 6f 6e 5f 69 64 20 5b 61 72 67 20 session_id [arg
22c0: 62 69 6e 61 72 79 5f 73 74 72 69 6e 67 5d 5d 0a binary_string]].
22d0: 53 70 65 63 69 66 69 65 73 20 74 68 65 20 73 65 Specifies the se
22e0: 73 73 69 6f 6e 20 69 64 20 74 6f 20 72 65 73 75 ssion id to resu
22f0: 6d 65 20 61 20 73 65 73 73 69 6f 6e 2e 20 4e 6f me a session. No
2300: 74 20 73 75 70 70 6f 72 74 65 64 20 79 65 74 2e t supported yet.
2310: 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 73 73 6c 32 ..[opt_def -ssl2
2320: 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 45 6e 61 [arg bool]].Ena
2330: 62 6c 65 20 75 73 65 20 6f 66 20 53 53 4c 20 76 ble use of SSL v
2340: 32 2e 54 68 65 20 64 65 66 61 75 6c 74 20 69 73 2.The default is
2350: 20 5b 63 6f 6e 73 74 20 66 61 6c 73 65 5d 2e 0a [const false]..
2360: 4f 70 65 6e 53 53 4c 20 31 2e 31 2b 20 6e 6f 20 OpenSSL 1.1+ no
2370: 6c 6f 6e 67 65 72 20 73 75 70 70 6f 72 74 73 20 longer supports
2380: 53 53 4c 20 76 32 2c 20 73 6f 20 74 68 69 73 20 SSL v2, so this
2390: 6d 61 79 20 6e 6f 74 20 68 61 76 65 20 61 6e 79 may not have any
23a0: 20 65 66 66 65 63 74 2e 0a 53 65 65 20 74 68 65 effect..See the
23b0: 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 72 6f 74 6f [cmd tls::proto
23c0: 63 6f 6c 73 5d 20 63 6f 6d 6d 61 6e 64 20 66 6f cols] command fo
23d0: 72 20 73 75 70 70 6f 72 74 65 64 20 70 72 6f 74 r supported prot
23e0: 6f 63 6f 6c 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 ocols...[opt_def
23f0: 20 2d 73 73 6c 33 20 5b 61 72 67 20 62 6f 6f 6c -ssl3 [arg bool
2400: 5d 5d 0a 45 6e 61 62 6c 65 20 75 73 65 20 6f 66 ]].Enable use of
2410: 20 53 53 4c 20 76 33 2e 20 54 68 65 20 64 65 66 SSL v3. The def
2420: 61 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 66 ault is [const f
2430: 61 6c 73 65 5d 2e 20 53 74 61 72 74 69 6e 67 20 alse]. Starting
2440: 69 6e 20 54 63 6c 54 4c 53 20 31 2e 38 2c 0a 75 in TclTLS 1.8,.u
2450: 73 65 20 6f 66 20 53 53 4c 20 76 33 20 69 66 20 se of SSL v3 if
2460: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 76 only available v
2470: 69 61 20 61 20 63 6f 6d 70 69 6c 65 20 74 69 6d ia a compile tim
2480: 65 20 6f 70 74 69 6f 6e 2e 0a 53 65 65 20 74 68 e option..See th
2490: 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 72 6f 74 e [cmd tls::prot
24a0: 6f 63 6f 6c 73 5d 20 63 6f 6d 6d 61 6e 64 20 66 ocols] command f
24b0: 6f 72 20 73 75 70 70 6f 72 74 65 64 20 70 72 6f or supported pro
24c0: 74 6f 63 6f 6c 73 2e 0a 0a 5b 6f 70 74 5f 64 65 tocols...[opt_de
24d0: 66 20 2d 74 6c 73 31 20 5b 61 72 67 20 62 6f 6f f -tls1 [arg boo
24e0: 6c 5d 5d 0a 45 6e 61 62 6c 65 20 75 73 65 20 6f l]].Enable use o
24f0: 66 20 54 4c 53 20 76 31 2e 20 53 74 61 72 74 69 f TLS v1. Starti
2500: 6e 67 20 69 6e 20 54 63 6c 54 4c 53 20 32 2e 30 ng in TclTLS 2.0
2510: 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 69 73 , the default is
2520: 20 5b 63 6f 6e 73 74 20 66 61 6c 73 65 5d 2e 0a [const false]..
2530: 4e 6f 74 65 3a 20 54 4c 53 20 31 2e 30 20 6e 65 Note: TLS 1.0 ne
2540: 65 64 73 20 53 48 41 31 20 74 6f 20 6f 70 65 72 eds SHA1 to oper
2550: 61 74 65 2c 20 77 68 69 63 68 20 69 73 20 6f 6e ate, which is on
2560: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 ly available in
2570: 73 65 63 75 72 69 74 79 20 6c 65 76 65 6c 0a 30 security level.0
2580: 20 66 6f 72 20 4f 70 65 6e 20 53 53 4c 20 33 2e for Open SSL 3.
2590: 30 2b 2e 20 53 65 65 20 74 68 65 20 5b 61 72 67 0+. See the [arg
25a0: 20 2d 73 65 63 75 72 69 74 79 5f 6c 65 76 65 6c -security_level
25b0: 5d 20 6f 70 74 69 6f 6e 2e 0a 0a 5b 6f 70 74 5f ] option...[opt_
25c0: 64 65 66 20 2d 74 6c 73 31 2e 31 20 5b 61 72 67 def -tls1.1 [arg
25d0: 20 62 6f 6f 6c 5d 5d 0a 45 6e 61 62 6c 65 20 75 bool]].Enable u
25e0: 73 65 20 6f 66 20 54 4c 53 20 76 31 2e 31 2e 20 se of TLS v1.1.
25f0: 53 74 61 72 74 69 6e 67 20 69 6e 20 54 63 6c 54 Starting in TclT
2600: 4c 53 20 32 2e 30 2c 20 74 68 65 20 64 65 66 61 LS 2.0, the defa
2610: 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 66 61 ult is [const fa
2620: 6c 73 65 5d 2e 0a 4e 6f 74 65 3a 20 54 4c 53 20 lse]..Note: TLS
2630: 31 2e 31 20 6e 65 65 64 73 20 53 48 41 31 20 74 1.1 needs SHA1 t
2640: 6f 20 6f 70 65 72 61 74 65 2c 20 77 68 69 63 68 o operate, which
2650: 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
2660: 6c 65 20 69 6e 20 73 65 63 75 72 69 74 79 20 6c le in security l
2670: 65 76 65 6c 0a 30 20 66 6f 72 20 4f 70 65 6e 20 evel.0 for Open
2680: 53 53 4c 20 33 2e 30 2b 2e 20 53 65 65 20 74 68 SSL 3.0+. See th
2690: 65 20 5b 61 72 67 20 2d 73 65 63 75 72 69 74 79 e [arg -security
26a0: 5f 6c 65 76 65 6c 5d 20 6f 70 74 69 6f 6e 2e 0a _level] option..
26b0: 0a 5b 6f 70 74 5f 64 65 66 20 2d 74 6c 73 31 2e .[opt_def -tls1.
26c0: 32 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d 0a 45 6e 2 [arg bool]].En
26d0: 61 62 6c 65 20 75 73 65 20 6f 66 20 54 4c 53 20 able use of TLS
26e0: 76 31 2e 32 2e 20 54 68 65 20 64 65 66 61 75 6c v1.2. The defaul
26f0: 74 20 69 73 20 5b 63 6f 6e 73 74 20 74 72 75 65 t is [const true
2700: 5d 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 74 6c ]...[opt_def -tl
2710: 73 31 2e 33 20 5b 61 72 67 20 62 6f 6f 6c 5d 5d s1.3 [arg bool]]
2720: 0a 45 6e 61 62 6c 65 20 75 73 65 20 6f 66 20 54 .Enable use of T
2730: 4c 53 20 76 31 2e 33 2e 20 54 68 65 20 64 65 66 LS v1.3. The def
2740: 61 75 6c 74 20 69 73 20 5b 63 6f 6e 73 74 20 74 ault is [const t
2750: 72 75 65 5d 2e 20 54 68 69 73 20 69 73 20 6f 6e rue]. This is on
2760: 6c 79 20 61 76 61 69 6c 61 62 6c 65 0a 73 74 61 ly available.sta
2770: 72 74 69 6e 67 20 77 69 74 68 20 4f 70 65 6e 53 rting with OpenS
2780: 53 4c 20 31 2e 31 2e 31 20 61 6e 64 20 54 63 6c SL 1.1.1 and Tcl
2790: 54 4c 53 20 31 2e 37 2e 0a 0a 5b 6f 70 74 5f 64 TLS 1.7...[opt_d
27a0: 65 66 20 2d 76 61 6c 69 64 61 74 65 63 6f 6d 6d ef -validatecomm
27b0: 61 6e 64 20 5b 61 72 67 20 63 61 6c 6c 62 61 63 and [arg callbac
27c0: 6b 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 68 k]].Specifies th
27d0: 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6d 6d 61 e callback comma
27e0: 6e 64 20 74 6f 20 69 6e 76 6f 6b 65 20 74 6f 20 nd to invoke to
27f0: 76 61 6c 69 64 61 74 65 20 74 68 65 20 70 65 65 validate the pee
2800: 72 20 63 65 72 74 69 66 69 63 61 74 65 73 0a 61 r certificates.a
2810: 6e 64 20 6f 74 68 65 72 20 63 6f 6e 66 69 67 20 nd other config
2820: 69 6e 66 6f 20 64 75 72 69 6e 67 20 74 68 65 20 info during the
2830: 70 72 6f 74 6f 63 6f 6c 20 6e 65 67 6f 74 69 61 protocol negotia
2840: 74 69 6f 6e 20 70 68 61 73 65 2e 20 54 68 69 73 tion phase. This
2850: 20 63 61 6e 20 62 65 20 75 73 65 64 0a 62 79 20 can be used.by
2860: 54 43 4c 20 73 63 72 69 70 74 73 20 74 6f 20 70 TCL scripts to p
2870: 65 72 66 6f 72 6d 20 74 68 65 69 72 20 6f 77 6e erform their own
2880: 20 43 65 72 74 69 66 69 63 61 74 65 20 56 61 6c Certificate Val
2890: 69 64 61 74 69 6f 6e 20 74 6f 20 73 75 70 70 6c idation to suppl
28a0: 65 6d 65 6e 74 20 74 68 65 0a 64 65 66 61 75 6c ement the.defaul
28b0: 74 20 76 61 6c 69 64 61 74 69 6f 6e 20 70 72 6f t validation pro
28c0: 76 69 64 65 64 20 62 79 20 4f 70 65 6e 53 53 4c vided by OpenSSL
28d0: 2e 20 54 68 65 20 73 63 72 69 70 74 20 6d 75 73 . The script mus
28e0: 74 20 72 65 74 75 72 6e 20 61 20 62 6f 6f 6c 65 t return a boole
28f0: 61 6e 20 74 72 75 65 0a 74 6f 20 63 6f 6e 74 69 an true.to conti
2900: 6e 75 65 20 74 68 65 20 6e 65 67 6f 74 69 61 74 nue the negotiat
2910: 69 6f 6e 2e 20 53 65 65 20 5b 73 65 63 74 72 65 ion. See [sectre
2920: 66 20 22 43 61 6c 6c 62 61 63 6b 20 4f 70 74 69 f "Callback Opti
2930: 6f 6e 73 22 5d 20 66 6f 72 20 6d 6f 72 65 20 69 ons"] for more i
2940: 6e 66 6f 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d nfo...[list_end]
2950: 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 ..[call [cmd tls
2960: 3a 3a 75 6e 69 6d 70 6f 72 74 5d 20 5b 61 72 67 ::unimport] [arg
2970: 20 63 68 61 6e 6e 65 6c 5d 5d 0a 0a 43 6f 6d 70 channel]]..Comp
2980: 6c 69 6d 65 6e 74 20 74 6f 20 5b 63 6d 64 20 74 liment to [cmd t
2990: 6c 73 3a 3a 69 6d 70 6f 72 74 5d 2e 20 55 73 65 ls::import]. Use
29a0: 64 20 74 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 d to remove the
29b0: 74 6f 70 20 6c 65 76 65 6c 20 73 74 61 63 6b 65 top level stacke
29c0: 64 20 63 68 61 6e 6e 65 6c 0a 66 72 6f 6d 20 5b d channel.from [
29d0: 61 72 67 20 63 68 61 6e 6e 65 6c 5d 2e 20 54 68 arg channel]. Th
29e0: 69 73 20 75 6e 73 74 61 63 6b 73 20 74 68 65 20 is unstacks the
29f0: 65 6e 63 72 79 70 74 69 6f 6e 20 6f 66 20 61 20 encryption of a
2a00: 72 65 67 75 6c 61 72 20 54 43 4c 20 63 68 61 6e regular TCL chan
2a10: 6e 65 6c 2e 20 41 6e 0a 65 72 72 6f 72 20 69 73 nel. An.error is
2a20: 20 74 68 72 6f 77 6e 20 69 66 20 54 4c 53 20 69 thrown if TLS i
2a30: 73 20 6e 6f 74 20 74 68 65 20 74 6f 70 20 73 74 s not the top st
2a40: 61 63 6b 65 64 20 63 68 61 6e 6e 65 6c 20 74 79 acked channel ty
2a50: 70 65 2e 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 pe...[call [cmd
2a60: 74 6c 73 3a 3a 68 61 6e 64 73 68 61 6b 65 5d 20 tls::handshake]
2a70: 5b 61 72 67 20 63 68 61 6e 6e 65 6c 5d 5d 0a 0a [arg channel]]..
2a80: 46 6f 72 63 65 73 20 74 68 65 20 54 4c 53 20 6e Forces the TLS n
2a90: 65 67 6f 74 69 61 74 69 6f 6e 20 68 61 6e 64 73 egotiation hands
2aa0: 68 61 6b 65 20 74 6f 20 74 61 6b 65 20 70 6c 61 hake to take pla
2ab0: 63 65 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 ce immediately,
2ac0: 61 6e 64 20 72 65 74 75 72 6e 73 20 30 0a 69 66 and returns 0.if
2ad0: 20 68 61 6e 64 73 68 61 6b 65 20 69 73 20 73 74 handshake is st
2ae0: 69 6c 6c 20 69 6e 20 70 72 6f 67 72 65 73 73 20 ill in progress
2af0: 28 6e 6f 6e 2d 62 6c 6f 63 6b 69 6e 67 29 2c 20 (non-blocking),
2b00: 6f 72 20 31 20 69 66 20 74 68 65 20 68 61 6e 64 or 1 if the hand
2b10: 73 68 61 6b 65 20 77 61 73 0a 73 75 63 63 65 73 shake was.succes
2b20: 73 66 75 6c 2e 20 49 66 20 74 68 65 20 68 61 6e sful. If the han
2b30: 64 73 68 61 6b 65 20 66 61 69 6c 65 64 2c 20 61 dshake failed, a
2b40: 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 n error will be
2b50: 72 65 74 75 72 6e 65 64 2e 0a 0a 5b 63 61 6c 6c returned...[call
2b60: 20 5b 63 6d 64 20 74 6c 73 3a 3a 73 74 61 74 75 [cmd tls::statu
2b70: 73 5d 20 5b 6f 70 74 20 5b 6f 70 74 69 6f 6e 20 s] [opt [option
2b80: 2d 6c 6f 63 61 6c 5d 5d 20 5b 61 72 67 20 63 68 -local]] [arg ch
2b90: 61 6e 6e 65 6c 5d 5d 0a 0a 52 65 74 75 72 6e 73 annel]]..Returns
2ba0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
2bb0: 74 75 73 20 6f 66 20 61 6e 20 53 53 4c 20 63 68 tus of an SSL ch
2bc0: 61 6e 6e 65 6c 2e 20 54 68 65 20 72 65 73 75 6c annel. The resul
2bd0: 74 20 69 73 20 61 20 6c 69 73 74 20 6f 66 20 6b t is a list of k
2be0: 65 79 2d 76 61 6c 75 65 0a 70 61 69 72 73 20 64 ey-value.pairs d
2bf0: 65 73 63 72 69 62 69 6e 67 20 74 68 65 20 53 53 escribing the SS
2c00: 4c 2c 20 63 65 72 74 69 66 69 63 61 74 65 2c 20 L, certificate,
2c10: 61 6e 64 20 63 65 72 74 69 66 69 63 61 74 65 20 and certificate
2c20: 76 65 72 69 66 69 63 61 74 69 6f 6e 20 73 74 61 verification sta
2c30: 74 75 73 2e 20 49 66 0a 74 68 65 20 53 53 4c 20 tus. If.the SSL
2c40: 68 61 6e 64 73 68 61 6b 65 20 68 61 73 20 6e 6f handshake has no
2c50: 74 20 79 65 74 20 63 6f 6d 70 6c 65 74 65 64 2c t yet completed,
2c60: 20 61 6e 20 65 6d 70 74 79 20 6c 69 73 74 20 69 an empty list i
2c70: 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 74 s returned. If t
2c80: 68 65 0a 5b 6f 70 74 69 6f 6e 20 2d 6c 6f 63 61 he.[option -loca
2c90: 6c 5d 20 6f 70 74 69 6f 6e 20 69 73 20 73 70 65 l] option is spe
2ca0: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 cified, then the
2cb0: 20 6c 6f 63 61 6c 20 63 65 72 74 69 66 69 63 61 local certifica
2cc0: 74 65 20 69 73 20 75 73 65 64 2e 20 52 65 74 75 te is used. Retu
2cd0: 72 6e 65 64 0a 76 61 6c 75 65 73 20 69 6e 63 6c rned.values incl
2ce0: 75 64 65 3a 0a 0a 5b 70 61 72 61 5d 0a 0a 53 53 ude:..[para]..SS
2cf0: 4c 20 53 74 61 74 75 73 0a 0a 5b 6c 69 73 74 5f L Status..[list_
2d00: 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 6f 6e begin definition
2d10: 73 5d 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 61 s]..[def "[var a
2d20: 6c 70 6e 5d 20 5b 61 72 67 20 70 72 6f 74 6f 63 lpn] [arg protoc
2d30: 6f 6c 5d 22 5d 0a 54 68 65 20 70 72 6f 74 6f 63 ol]"].The protoc
2d40: 6f 6c 20 73 65 6c 65 63 74 65 64 20 61 66 74 65 ol selected afte
2d50: 72 20 41 70 70 6c 69 63 61 74 69 6f 6e 2d 4c 61 r Application-La
2d60: 79 65 72 20 50 72 6f 74 6f 63 6f 6c 20 4e 65 67 yer Protocol Neg
2d70: 6f 74 69 61 74 69 6f 6e 20 28 41 4c 50 4e 29 2e otiation (ALPN).
2d80: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 63 69 70 ..[def "[var cip
2d90: 68 65 72 5d 20 5b 61 72 67 20 63 69 70 68 65 72 her] [arg cipher
2da0: 5d 22 5d 0a 54 68 65 20 63 75 72 72 65 6e 74 20 ]"].The current
2db0: 63 69 70 68 65 72 20 69 6e 20 75 73 65 20 66 6f cipher in use fo
2dc0: 72 20 74 68 65 20 73 65 73 73 69 6f 6e 2e 0a 0a r the session...
2dd0: 5b 64 65 66 20 22 5b 76 61 72 20 70 65 65 72 6e [def "[var peern
2de0: 61 6d 65 5d 20 5b 61 72 67 20 6e 61 6d 65 5d 22 ame] [arg name]"
2df0: 5d 0a 54 68 65 20 70 65 65 72 6e 61 6d 65 20 66 ].The peername f
2e00: 72 6f 6d 20 74 68 65 20 63 65 72 74 69 66 69 63 rom the certific
2e10: 61 74 65 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 ate...[def "[var
2e20: 20 70 72 6f 74 6f 63 6f 6c 5d 20 5b 61 72 67 20 protocol] [arg
2e30: 76 65 72 73 69 6f 6e 5d 22 5d 0a 54 68 65 20 70 version]"].The p
2e40: 72 6f 74 6f 63 6f 6c 20 76 65 72 73 69 6f 6e 20 rotocol version
2e50: 75 73 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e used for the con
2e60: 6e 65 63 74 69 6f 6e 3a 20 53 53 4c 32 2c 20 53 nection: SSL2, S
2e70: 53 4c 33 2c 20 54 4c 53 31 2c 20 54 4c 53 31 2e SL3, TLS1, TLS1.
2e80: 31 2c 20 54 4c 53 31 2e 32 2c 20 54 4c 53 31 2e 1, TLS1.2, TLS1.
2e90: 33 2c 20 6f 72 20 75 6e 6b 6e 6f 77 6e 2e 0a 0a 3, or unknown...
2ea0: 5b 64 65 66 20 22 5b 76 61 72 20 73 62 69 74 73 [def "[var sbits
2eb0: 5d 20 5b 61 72 67 20 6e 5d 22 5d 0a 54 68 65 20 ] [arg n]"].The
2ec0: 6e 75 6d 62 65 72 20 6f 66 20 62 69 74 73 20 75 number of bits u
2ed0: 73 65 64 20 66 6f 72 20 74 68 65 20 73 65 73 73 sed for the sess
2ee0: 69 6f 6e 20 6b 65 79 2e 0a 0a 5b 64 65 66 20 22 ion key...[def "
2ef0: 5b 76 61 72 20 73 69 67 6e 61 74 75 72 65 48 61 [var signatureHa
2f00: 73 68 41 6c 67 6f 72 69 74 68 6d 5d 20 5b 61 72 shAlgorithm] [ar
2f10: 67 20 61 6c 67 6f 72 69 74 68 6d 5d 22 5d 0a 54 g algorithm]"].T
2f20: 68 65 20 73 69 67 6e 61 74 75 72 65 20 68 61 73 he signature has
2f30: 68 20 61 6c 67 6f 72 69 74 68 6d 2e 0a 0a 5b 64 h algorithm...[d
2f40: 65 66 20 22 5b 76 61 72 20 73 69 67 6e 61 74 75 ef "[var signatu
2f50: 72 65 54 79 70 65 5d 20 5b 61 72 67 20 74 79 70 reType] [arg typ
2f60: 65 5d 22 5d 0a 54 68 65 20 73 69 67 6e 61 74 75 e]"].The signatu
2f70: 72 65 20 74 79 70 65 20 76 61 6c 75 65 2e 0a 0a re type value...
2f80: 5b 64 65 66 20 22 5b 76 61 72 20 76 65 72 69 66 [def "[var verif
2f90: 79 44 65 70 74 68 5d 20 5b 61 72 67 20 6e 5d 22 yDepth] [arg n]"
2fa0: 5d 0a 4d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 ].Maximum depth
2fb0: 66 6f 72 20 74 68 65 20 63 65 72 74 69 66 69 63 for the certific
2fc0: 61 74 65 20 63 68 61 69 6e 20 76 65 72 69 66 69 ate chain verifi
2fd0: 63 61 74 69 6f 6e 2e 20 44 65 66 61 75 6c 74 20 cation. Default
2fe0: 69 73 20 2d 31 2c 20 74 6f 20 63 68 65 63 6b 20 is -1, to check
2ff0: 61 6c 6c 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 all...[def "[var
3000: 20 76 65 72 69 66 79 4d 6f 64 65 5d 20 5b 61 72 verifyMode] [ar
3010: 67 20 6c 69 73 74 5d 22 5d 0a 4c 69 73 74 20 6f g list]"].List o
3020: 66 20 63 65 72 74 69 66 69 63 61 74 65 20 76 65 f certificate ve
3030: 72 69 66 69 63 61 74 69 6f 6e 20 6d 6f 64 65 73 rification modes
3040: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 76 65 ...[def "[var ve
3050: 72 69 66 79 52 65 73 75 6c 74 5d 20 5b 61 72 67 rifyResult] [arg
3060: 20 72 65 73 75 6c 74 5d 22 5d 0a 43 65 72 74 69 result]"].Certi
3070: 66 69 63 61 74 65 20 76 65 72 69 66 69 63 61 74 ficate verificat
3080: 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 0a 5b 64 65 ion result...[de
3090: 66 20 22 5b 76 61 72 20 63 61 5f 6e 61 6d 65 73 f "[var ca_names
30a0: 5d 20 5b 61 72 67 20 6c 69 73 74 5d 22 5d 0a 4c ] [arg list]"].L
30b0: 69 73 74 20 6f 66 20 74 68 65 20 43 65 72 74 69 ist of the Certi
30c0: 66 69 63 61 74 65 20 41 75 74 68 6f 72 69 74 69 ficate Authoriti
30d0: 65 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 es used to creat
30e0: 65 20 74 68 65 20 63 65 72 74 69 66 69 63 61 74 e the certificat
30f0: 65 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a e...[list_end]..
3100: 43 65 72 74 69 66 69 63 61 74 65 20 53 74 61 74 Certificate Stat
3110: 75 73 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e 20 us..[list_begin
3120: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a 5b 64 definitions]..[d
3130: 65 66 20 22 5b 76 61 72 20 61 6c 6c 5d 20 5b 61 ef "[var all] [a
3140: 72 67 20 73 74 72 69 6e 67 5d 22 5d 0a 44 75 6d rg string]"].Dum
3150: 70 20 6f 66 20 61 6c 6c 20 63 65 72 74 69 66 69 p of all certifi
3160: 63 61 74 65 20 69 6e 66 6f 2e 0a 0a 5b 64 65 66 cate info...[def
3170: 20 22 5b 76 61 72 20 76 65 72 73 69 6f 6e 5d 20 "[var version]
3180: 5b 61 72 67 20 76 61 6c 75 65 5d 22 5d 0a 54 68 [arg value]"].Th
3190: 65 20 63 65 72 74 69 66 69 63 61 74 65 20 76 65 e certificate ve
31a0: 72 73 69 6f 6e 2e 0a 0a 5b 64 65 66 20 22 5b 76 rsion...[def "[v
31b0: 61 72 20 73 65 72 69 61 6c 4e 75 6d 62 65 72 5d ar serialNumber]
31c0: 20 5b 61 72 67 20 73 74 72 69 6e 67 5d 22 5d 0a [arg string]"].
31d0: 54 68 65 20 73 65 72 69 61 6c 20 6e 75 6d 62 65 The serial numbe
31e0: 72 20 6f 66 20 74 68 65 20 63 65 72 74 69 66 69 r of the certifi
31f0: 63 61 74 65 20 61 73 20 61 20 68 65 78 20 73 74 cate as a hex st
3200: 72 69 6e 67 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 ring...[def "[va
3210: 72 20 73 69 67 6e 61 74 75 72 65 5d 20 5b 61 72 r signature] [ar
3220: 67 20 61 6c 67 6f 72 69 74 68 6d 5d 22 5d 0a 43 g algorithm]"].C
3230: 69 70 68 65 72 20 61 6c 67 6f 72 69 74 68 6d 20 ipher algorithm
3240: 75 73 65 64 20 66 6f 72 20 63 65 72 74 69 66 69 used for certifi
3250: 63 61 74 65 20 73 69 67 6e 61 74 75 72 65 2e 0a cate signature..
3260: 0a 5b 64 65 66 20 22 5b 76 61 72 20 69 73 73 75 .[def "[var issu
3270: 65 72 5d 20 5b 61 72 67 20 73 74 72 69 6e 67 5d er] [arg string]
3280: 22 5d 0a 54 68 65 20 64 69 73 74 69 6e 67 75 69 "].The distingui
3290: 73 68 65 64 20 6e 61 6d 65 20 28 44 4e 29 20 6f shed name (DN) o
32a0: 66 20 74 68 65 20 63 65 72 74 69 66 69 63 61 74 f the certificat
32b0: 65 20 69 73 73 75 65 72 2e 0a 0a 5b 64 65 66 20 e issuer...[def
32c0: 22 5b 76 61 72 20 6e 6f 74 42 65 66 6f 72 65 5d "[var notBefore]
32d0: 20 5b 61 72 67 20 64 61 74 65 5d 22 5d 0a 54 68 [arg date]"].Th
32e0: 65 20 62 65 67 69 6e 6e 69 6e 67 20 64 61 74 65 e beginning date
32f0: 20 6f 66 20 74 68 65 20 63 65 72 74 69 66 69 63 of the certific
3300: 61 74 65 20 76 61 6c 69 64 69 74 79 2e 0a 0a 5b ate validity...[
3310: 64 65 66 20 22 5b 76 61 72 20 6e 6f 74 41 66 74 def "[var notAft
3320: 65 72 5d 20 5b 61 72 67 20 64 61 74 65 5d 22 5d er] [arg date]"]
3330: 0a 54 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 .The expiration
3340: 64 61 74 65 20 6f 66 20 74 68 65 20 63 65 72 74 date of the cert
3350: 69 66 69 63 61 74 65 20 76 61 6c 69 64 69 74 79 ificate validity
3360: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 75 ...[def "[var su
3370: 62 6a 65 63 74 5d 20 5b 61 72 67 20 73 74 72 69 bject] [arg stri
3380: 6e 67 5d 22 5d 0a 54 68 65 20 64 69 73 74 69 6e ng]"].The distin
3390: 67 75 69 73 68 65 64 20 6e 61 6d 65 20 28 44 4e guished name (DN
33a0: 29 20 6f 66 20 74 68 65 20 63 65 72 74 69 66 69 ) of the certifi
33b0: 63 61 74 65 20 73 75 62 6a 65 63 74 2e 20 46 69 cate subject. Fi
33c0: 65 6c 64 73 20 69 6e 63 6c 75 64 65 3a 20 43 6f elds include: Co
33d0: 6d 6d 6f 6e 0a 4e 61 6d 65 20 28 43 4e 29 2c 20 mmon.Name (CN),
33e0: 4f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 28 4f 29 Organization (O)
33f0: 2c 20 4c 6f 63 61 6c 69 74 79 20 6f 72 20 43 69 , Locality or Ci
3400: 74 79 20 28 4c 29 2c 20 53 74 61 74 65 20 6f 72 ty (L), State or
3410: 20 50 72 6f 76 69 6e 63 65 20 28 53 29 2c 20 61 Province (S), a
3420: 6e 64 0a 43 6f 75 6e 74 72 79 20 4e 61 6d 65 20 nd.Country Name
3430: 28 43 29 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 (C)...[def "[var
3440: 20 69 73 73 75 65 72 55 6e 69 71 75 65 49 44 5d issuerUniqueID]
3450: 20 5b 61 72 67 20 73 74 72 69 6e 67 5d 22 5d 0a [arg string]"].
3460: 54 68 65 20 69 73 73 75 65 72 20 75 6e 69 71 75 The issuer uniqu
3470: 65 20 69 64 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 e id...[def "[va
3480: 72 20 73 75 62 6a 65 63 74 55 6e 69 71 75 65 49 r subjectUniqueI
3490: 44 5d 20 5b 61 72 67 20 73 74 72 69 6e 67 5d 22 D] [arg string]"
34a0: 5d 0a 54 68 65 20 73 75 62 6a 65 63 74 20 75 6e ].The subject un
34b0: 69 71 75 65 20 69 64 2e 0a 0a 5b 64 65 66 20 22 ique id...[def "
34c0: 5b 76 61 72 20 6e 75 6d 5f 65 78 74 65 6e 73 69 [var num_extensi
34d0: 6f 6e 73 5d 20 5b 61 72 67 20 6e 5d 22 5d 0a 4e ons] [arg n]"].N
34e0: 75 6d 62 65 72 20 6f 66 20 63 65 72 74 69 66 69 umber of certifi
34f0: 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 2e cate extensions.
3500: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 65 78 74 ..[def "[var ext
3510: 65 6e 73 69 6f 6e 73 5d 20 5b 61 72 67 20 6c 69 ensions] [arg li
3520: 73 74 5d 22 5d 0a 4c 69 73 74 20 6f 66 20 63 65 st]"].List of ce
3530: 72 74 69 66 69 63 61 74 65 20 65 78 74 65 6e 73 rtificate extens
3540: 69 6f 6e 20 6e 61 6d 65 73 2e 0a 0a 5b 64 65 66 ion names...[def
3550: 20 22 5b 76 61 72 20 61 75 74 68 6f 72 69 74 79 "[var authority
3560: 4b 65 79 49 64 65 6e 74 69 66 69 65 72 5d 20 5b KeyIdentifier] [
3570: 61 72 67 20 73 74 72 69 6e 67 5d 22 5d 0a 41 75 arg string]"].Au
3580: 74 68 6f 72 69 74 79 20 4b 65 79 20 49 64 65 6e thority Key Iden
3590: 74 69 66 69 65 72 20 28 41 4b 49 29 20 6f 66 20 tifier (AKI) of
35a0: 74 68 65 20 49 73 73 75 69 6e 67 20 43 41 20 63 the Issuing CA c
35b0: 65 72 74 69 66 69 63 61 74 65 20 74 68 61 74 20 ertificate that
35c0: 73 69 67 6e 65 64 20 74 68 65 0a 53 53 4c 20 63 signed the.SSL c
35d0: 65 72 74 69 66 69 63 61 74 65 20 61 73 20 61 20 ertificate as a
35e0: 68 65 78 20 73 74 72 69 6e 67 2e 20 54 68 69 73 hex string. This
35f0: 20 76 61 6c 75 65 20 6d 61 74 63 68 65 73 20 74 value matches t
3600: 68 65 20 53 4b 49 20 76 61 6c 75 65 20 6f 66 20 he SKI value of
3610: 74 68 65 0a 49 6e 74 65 72 6d 65 64 69 61 74 65 the.Intermediate
3620: 20 43 41 20 63 65 72 74 69 66 69 63 61 74 65 2e CA certificate.
3630: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 75 62 ..[def "[var sub
3640: 6a 65 63 74 4b 65 79 49 64 65 6e 74 69 66 69 65 jectKeyIdentifie
3650: 72 5d 20 5b 61 72 67 20 73 74 72 69 6e 67 5d 22 r] [arg string]"
3660: 5d 0a 53 75 62 6a 65 63 74 20 4b 65 79 20 49 64 ].Subject Key Id
3670: 65 6e 74 69 66 69 65 72 20 28 53 4b 49 29 20 68 entifier (SKI) h
3680: 61 73 68 20 6f 66 20 74 68 65 20 70 75 62 6c 69 ash of the publi
3690: 63 20 6b 65 79 20 69 6e 73 69 64 65 20 74 68 65 c key inside the
36a0: 20 63 65 72 74 69 66 69 63 61 74 65 20 61 73 20 certificate as
36b0: 61 0a 68 65 78 20 73 74 72 69 6e 67 2e 20 55 73 a.hex string. Us
36c0: 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 63 ed to identify c
36d0: 65 72 74 69 66 69 63 61 74 65 73 20 74 68 61 74 ertificates that
36e0: 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 contain a parti
36f0: 63 75 6c 61 72 20 70 75 62 6c 69 63 20 6b 65 79 cular public key
3700: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 75 ...[def "[var su
3710: 62 6a 65 63 74 41 6c 74 4e 61 6d 65 5d 20 5b 61 bjectAltName] [a
3720: 72 67 20 6c 69 73 74 5d 22 5d 0a 4c 69 73 74 20 rg list]"].List
3730: 6f 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 53 75 of all of the Su
3740: 62 6a 65 63 74 20 41 6c 74 65 72 6e 61 74 69 76 bject Alternativ
3750: 65 20 4e 61 6d 65 73 20 28 53 41 4e 29 20 69 6e e Names (SAN) in
3760: 63 6c 75 64 69 6e 67 20 64 6f 6d 61 69 6e 20 6e cluding domain n
3770: 61 6d 65 73 2c 20 73 75 62 0a 64 6f 6d 61 69 6e ames, sub.domain
3780: 73 2c 20 61 6e 64 20 49 50 20 61 64 64 72 65 73 s, and IP addres
3790: 73 65 73 20 74 68 61 74 20 61 72 65 20 73 65 63 ses that are sec
37a0: 75 72 65 64 20 62 79 20 74 68 65 20 63 65 72 74 ured by the cert
37b0: 69 66 69 63 61 74 65 2e 0a 0a 5b 64 65 66 20 22 ificate...[def "
37c0: 5b 76 61 72 20 6f 63 73 70 5d 20 5b 61 72 67 20 [var ocsp] [arg
37d0: 6c 69 73 74 5d 22 5d 0a 4c 69 73 74 20 6f 66 20 list]"].List of
37e0: 61 6c 6c 20 4f 6e 6c 69 6e 65 20 43 65 72 74 69 all Online Certi
37f0: 66 69 63 61 74 65 20 53 74 61 74 75 73 20 50 72 ficate Status Pr
3800: 6f 74 6f 63 6f 6c 20 28 4f 43 53 50 29 20 55 52 otocol (OCSP) UR
3810: 4c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 Ls that can be u
3820: 73 65 64 20 74 6f 0a 63 68 65 63 6b 20 74 68 65 sed to.check the
3830: 20 76 61 6c 69 64 69 74 79 20 6f 66 20 74 68 69 validity of thi
3840: 73 20 63 65 72 74 69 66 69 63 61 74 65 2e 0a 0a s certificate...
3850: 5b 64 65 66 20 22 5b 76 61 72 20 63 65 72 74 69 [def "[var certi
3860: 66 69 63 61 74 65 5d 20 5b 61 72 67 20 63 65 72 ficate] [arg cer
3870: 74 5d 22 5d 0a 54 68 65 20 50 45 4d 20 65 6e 63 t]"].The PEM enc
3880: 6f 64 65 64 20 63 65 72 74 69 66 69 63 61 74 65 oded certificate
3890: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 69 ...[def "[var si
38a0: 67 6e 61 74 75 72 65 41 6c 67 6f 72 69 74 68 6d gnatureAlgorithm
38b0: 5d 20 5b 61 72 67 20 61 6c 67 6f 72 69 74 68 6d ] [arg algorithm
38c0: 5d 22 5d 0a 43 69 70 68 65 72 20 61 6c 67 6f 72 ]"].Cipher algor
38d0: 69 74 68 6d 20 75 73 65 64 20 66 6f 72 20 74 68 ithm used for th
38e0: 65 20 63 65 72 74 69 66 69 63 61 74 65 20 73 69 e certificate si
38f0: 67 6e 61 74 75 72 65 2e 0a 0a 5b 64 65 66 20 22 gnature...[def "
3900: 5b 76 61 72 20 73 69 67 6e 61 74 75 72 65 56 61 [var signatureVa
3910: 6c 75 65 5d 20 5b 61 72 67 20 73 74 72 69 6e 67 lue] [arg string
3920: 5d 22 5d 0a 43 65 72 74 69 66 69 63 61 74 65 20 ]"].Certificate
3930: 73 69 67 6e 61 74 75 72 65 20 61 73 20 61 20 68 signature as a h
3940: 65 78 20 73 74 72 69 6e 67 2e 0a 0a 5b 64 65 66 ex string...[def
3950: 20 22 5b 76 61 72 20 73 69 67 6e 61 74 75 72 65 "[var signature
3960: 44 69 67 65 73 74 5d 20 5b 61 72 67 20 76 65 72 Digest] [arg ver
3970: 73 69 6f 6e 5d 22 5d 0a 43 65 72 74 69 66 69 63 sion]"].Certific
3980: 61 74 65 20 73 69 67 6e 69 6e 67 20 64 69 67 65 ate signing dige
3990: 73 74 20 61 73 20 61 20 68 65 78 20 73 74 72 69 st as a hex stri
39a0: 6e 67 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 ng...[def "[var
39b0: 70 75 62 6c 69 63 4b 65 79 41 6c 67 6f 72 69 74 publicKeyAlgorit
39c0: 68 6d 5d 20 5b 61 72 67 20 61 6c 67 6f 72 69 74 hm] [arg algorit
39d0: 68 6d 5d 22 5d 0a 43 65 72 74 69 66 69 63 61 74 hm]"].Certificat
39e0: 65 20 73 69 67 6e 61 74 75 72 65 20 70 75 62 6c e signature publ
39f0: 69 63 20 6b 65 79 20 61 6c 67 6f 72 69 74 68 6d ic key algorithm
3a00: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 70 75 ...[def "[var pu
3a10: 62 6c 69 63 4b 65 79 5d 20 5b 61 72 67 20 73 74 blicKey] [arg st
3a20: 72 69 6e 67 5d 22 5d 0a 43 65 72 74 69 66 69 63 ring]"].Certific
3a30: 61 74 65 20 73 69 67 6e 61 74 75 72 65 20 70 75 ate signature pu
3a40: 62 6c 69 63 20 6b 65 79 20 61 73 20 61 20 68 65 blic key as a he
3a50: 78 20 73 74 72 69 6e 67 2e 0a 0a 5b 64 65 66 20 x string...[def
3a60: 22 5b 76 61 72 20 62 69 74 73 5d 20 5b 61 72 67 "[var bits] [arg
3a70: 20 6e 5d 22 5d 0a 4e 75 6d 62 65 72 20 6f 66 20 n]"].Number of
3a80: 62 69 74 73 20 75 73 65 64 20 66 6f 72 20 63 65 bits used for ce
3a90: 72 74 69 66 69 63 61 74 65 20 73 69 67 6e 61 74 rtificate signat
3aa0: 75 72 65 20 6b 65 79 2e 0a 0a 5b 64 65 66 20 22 ure key...[def "
3ab0: 5b 76 61 72 20 73 65 6c 66 5f 73 69 67 6e 65 64 [var self_signed
3ac0: 5d 20 5b 61 72 67 20 62 6f 6f 6c 65 61 6e 5d 22 ] [arg boolean]"
3ad0: 5d 0a 57 68 65 74 68 65 72 20 74 68 65 20 63 65 ].Whether the ce
3ae0: 72 74 69 66 69 63 61 74 65 20 73 69 67 6e 61 74 rtificate signat
3af0: 75 72 65 20 69 73 20 73 65 6c 66 20 73 69 67 6e ure is self sign
3b00: 65 64 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 ed...[def "[var
3b10: 73 68 61 31 5f 68 61 73 68 5d 20 5b 61 72 67 20 sha1_hash] [arg
3b20: 68 61 73 68 5d 22 5d 0a 54 68 65 20 53 48 41 31 hash]"].The SHA1
3b30: 20 68 61 73 68 20 6f 66 20 74 68 65 20 63 65 72 hash of the cer
3b40: 74 69 66 69 63 61 74 65 20 61 73 20 61 20 68 65 tificate as a he
3b50: 78 20 73 74 72 69 6e 67 2e 0a 0a 5b 64 65 66 20 x string...[def
3b60: 22 5b 76 61 72 20 73 68 61 32 35 36 5f 68 61 73 "[var sha256_has
3b70: 68 5d 20 5b 61 72 67 20 68 61 73 68 5d 22 5d 0a h] [arg hash]"].
3b80: 54 68 65 20 53 48 41 32 35 36 20 68 61 73 68 20 The SHA256 hash
3b90: 6f 66 20 74 68 65 20 63 65 72 74 69 66 69 63 61 of the certifica
3ba0: 74 65 20 61 73 20 61 20 68 65 78 20 73 74 72 69 te as a hex stri
3bb0: 6e 67 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a ng...[list_end].
3bc0: 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 3a .[call [cmd tls:
3bd0: 3a 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 5b 61 72 :connection] [ar
3be0: 67 20 63 68 61 6e 6e 65 6c 5d 5d 0a 0a 52 65 74 g channel]]..Ret
3bf0: 75 72 6e 73 20 74 68 65 20 63 75 72 72 65 6e 74 urns the current
3c00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 74 61 74 connection stat
3c10: 75 73 20 6f 66 20 61 6e 20 53 53 4c 20 63 68 61 us of an SSL cha
3c20: 6e 6e 65 6c 2e 20 54 68 65 20 72 65 73 75 6c 74 nnel. The result
3c30: 20 69 73 20 61 20 6c 69 73 74 0a 6f 66 20 6b 65 is a list.of ke
3c40: 79 2d 76 61 6c 75 65 20 70 61 69 72 73 20 64 65 y-value pairs de
3c50: 73 63 72 69 62 69 6e 67 20 74 68 65 20 63 6f 6e scribing the con
3c60: 6e 65 63 74 69 6f 6e 2e 20 52 65 74 75 72 6e 65 nection. Returne
3c70: 64 20 76 61 6c 75 65 73 20 69 6e 63 6c 75 64 65 d values include
3c80: 3a 0a 0a 5b 70 61 72 61 5d 0a 0a 53 53 4c 20 53 :..[para]..SSL S
3c90: 74 61 74 75 73 0a 0a 5b 6c 69 73 74 5f 62 65 67 tatus..[list_beg
3ca0: 69 6e 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a in definitions].
3cb0: 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 74 61 74 .[def "[var stat
3cc0: 65 5d 20 5b 61 72 67 20 73 74 61 74 65 5d 22 5d e] [arg state]"]
3cd0: 0a 53 74 61 74 65 20 6f 66 20 74 68 65 20 63 6f .State of the co
3ce0: 6e 6e 65 63 74 69 6f 6e 2e 0a 0a 5b 64 65 66 20 nnection...[def
3cf0: 22 5b 76 61 72 20 73 65 72 76 65 72 6e 61 6d 65 "[var servername
3d00: 5d 20 5b 61 72 67 20 6e 61 6d 65 5d 22 5d 0a 54 ] [arg name]"].T
3d10: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
3d20: 6f 6e 6e 65 63 74 65 64 20 74 6f 20 73 65 72 76 onnected to serv
3d30: 65 72 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 er...[def "[var
3d40: 70 72 6f 74 6f 63 6f 6c 5d 20 5b 61 72 67 20 76 protocol] [arg v
3d50: 65 72 73 69 6f 6e 5d 22 5d 0a 54 68 65 20 70 72 ersion]"].The pr
3d60: 6f 74 6f 63 6f 6c 20 76 65 72 73 69 6f 6e 20 75 otocol version u
3d70: 73 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e sed for the conn
3d80: 65 63 74 69 6f 6e 3a 20 53 53 4c 32 2c 20 53 53 ection: SSL2, SS
3d90: 4c 33 2c 20 54 4c 53 31 2c 20 54 4c 53 31 2e 31 L3, TLS1, TLS1.1
3da0: 2c 20 54 4c 53 31 2e 32 2c 20 54 4c 53 31 2e 33 , TLS1.2, TLS1.3
3db0: 2c 20 6f 72 20 75 6e 6b 6e 6f 77 6e 2e 0a 0a 5b , or unknown...[
3dc0: 64 65 66 20 22 5b 76 61 72 20 72 65 6e 65 67 6f def "[var renego
3dd0: 74 69 61 74 69 6f 6e 5f 61 6c 6c 6f 77 65 64 5d tiation_allowed]
3de0: 20 5b 61 72 67 20 62 6f 6f 6c 65 61 6e 5d 22 5d [arg boolean]"]
3df0: 0a 57 68 65 74 68 65 72 20 70 72 6f 74 6f 63 6f .Whether protoco
3e00: 6c 20 72 65 6e 65 67 6f 74 69 61 74 69 6f 6e 20 l renegotiation
3e10: 69 73 20 73 75 70 70 6f 72 74 65 64 20 6f 72 20 is supported or
3e20: 6e 6f 74 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 not...[def "[var
3e30: 20 73 65 63 75 72 69 74 79 5f 6c 65 76 65 6c 5d security_level]
3e40: 20 5b 61 72 67 20 6c 65 76 65 6c 5d 22 5d 0a 54 [arg level]"].T
3e50: 68 65 20 73 65 63 75 72 69 74 79 20 6c 65 76 65 he security leve
3e60: 6c 20 75 73 65 64 20 66 6f 72 20 73 65 6c 65 63 l used for selec
3e70: 74 69 6f 6e 20 6f 66 20 63 69 70 68 65 72 73 2c tion of ciphers,
3e80: 20 6b 65 79 20 73 69 7a 65 2c 20 65 74 63 2e 0a key size, etc..
3e90: 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 65 73 73 .[def "[var sess
3ea0: 69 6f 6e 5f 72 65 75 73 65 64 5d 20 5b 61 72 67 ion_reused] [arg
3eb0: 20 62 6f 6f 6c 65 61 6e 5d 22 5d 0a 57 68 65 74 boolean]"].Whet
3ec0: 68 65 72 20 74 68 65 20 73 65 73 73 69 6f 6e 20 her the session
3ed0: 68 61 73 20 62 65 65 6e 20 72 65 75 73 65 64 20 has been reused
3ee0: 6f 72 20 6e 6f 74 2e 0a 0a 5b 64 65 66 20 22 5b or not...[def "[
3ef0: 76 61 72 20 69 73 5f 73 65 72 76 65 72 5d 20 5b var is_server] [
3f00: 61 72 67 20 62 6f 6f 6c 65 61 6e 5d 22 5d 0a 57 arg boolean]"].W
3f10: 68 65 74 68 65 72 20 74 68 65 20 63 6f 6e 6e 65 hether the conne
3f20: 63 74 69 6f 6e 20 69 73 20 63 6f 6e 66 69 67 75 ction is configu
3f30: 72 65 64 20 61 73 20 61 20 73 65 72 76 65 72 20 red as a server
3f40: 28 31 29 20 6f 72 20 63 6c 69 65 6e 74 20 28 30 (1) or client (0
3f50: 29 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 63 )...[def "[var c
3f60: 6f 6d 70 72 65 73 73 69 6f 6e 5d 20 5b 61 72 67 ompression] [arg
3f70: 20 6d 6f 64 65 5d 22 5d 0a 43 6f 6d 70 72 65 73 mode]"].Compres
3f80: 73 69 6f 6e 20 6d 65 74 68 6f 64 2e 0a 0a 5b 64 sion method...[d
3f90: 65 66 20 22 5b 76 61 72 20 65 78 70 61 6e 73 69 ef "[var expansi
3fa0: 6f 6e 5d 20 5b 61 72 67 20 6d 6f 64 65 5d 22 5d on] [arg mode]"]
3fb0: 0a 45 78 70 61 6e 73 69 6f 6e 20 6d 65 74 68 6f .Expansion metho
3fc0: 64 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 63 d...[def "[var c
3fd0: 61 4c 69 73 74 5d 20 5b 61 72 67 20 6c 69 73 74 aList] [arg list
3fe0: 5d 22 5d 0a 4c 69 73 74 20 6f 66 20 43 65 72 74 ]"].List of Cert
3ff0: 69 66 69 63 61 74 65 20 41 75 74 68 6f 72 69 74 ificate Authorit
4000: 69 65 73 20 28 43 41 29 20 66 6f 72 20 58 2e 35 ies (CA) for X.5
4010: 30 39 20 63 65 72 74 69 66 69 63 61 74 65 2e 0a 09 certificate..
4020: 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 43 69 70 .[list_end]..Cip
4030: 68 65 72 20 49 6e 66 6f 0a 0a 5b 6c 69 73 74 5f her Info..[list_
4040: 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 6f 6e begin definition
4050: 73 5d 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 63 s]..[def "[var c
4060: 69 70 68 65 72 5d 20 5b 61 72 67 20 63 69 70 68 ipher] [arg ciph
4070: 65 72 5d 22 5d 0a 54 68 65 20 63 75 72 72 65 6e er]"].The curren
4080: 74 20 63 69 70 68 65 72 20 69 6e 20 75 73 65 20 t cipher in use
4090: 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 for the connecti
40a0: 6f 6e 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 on...[def "[var
40b0: 73 74 61 6e 64 61 72 64 5f 6e 61 6d 65 5d 20 5b standard_name] [
40c0: 61 72 67 20 6e 61 6d 65 5d 22 5d 0a 54 68 65 20 arg name]"].The
40d0: 73 74 61 6e 64 61 72 64 20 52 46 43 20 6e 61 6d standard RFC nam
40e0: 65 20 6f 66 20 63 69 70 68 65 72 2e 0a 0a 5b 64 e of cipher...[d
40f0: 65 66 20 22 5b 76 61 72 20 61 6c 67 6f 72 69 74 ef "[var algorit
4100: 68 6d 5f 62 69 74 73 5d 20 5b 61 72 67 20 6e 5d hm_bits] [arg n]
4110: 22 5d 0a 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 "].The number of
4120: 20 70 72 6f 63 65 73 73 65 64 20 62 69 74 73 20 processed bits
4130: 75 73 65 64 20 66 6f 72 20 63 69 70 68 65 72 2e used for cipher.
4140: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 65 63 ..[def "[var sec
4150: 72 65 74 5f 62 69 74 73 5d 20 5b 61 72 67 20 6e ret_bits] [arg n
4160: 5d 22 5d 0a 54 68 65 20 6e 75 6d 62 65 72 20 6f ]"].The number o
4170: 66 20 73 65 63 72 65 74 20 62 69 74 73 20 75 73 f secret bits us
4180: 65 64 20 66 6f 72 20 63 69 70 68 65 72 2e 0a 0a ed for cipher...
4190: 5b 64 65 66 20 22 5b 76 61 72 20 6d 69 6e 5f 76 [def "[var min_v
41a0: 65 72 73 69 6f 6e 5d 20 5b 61 72 67 20 76 65 72 ersion] [arg ver
41b0: 73 69 6f 6e 5d 22 5d 0a 54 68 65 20 6d 69 6e 69 sion]"].The mini
41c0: 6d 75 6d 20 70 72 6f 74 6f 63 6f 6c 20 76 65 72 mum protocol ver
41d0: 73 69 6f 6e 20 66 6f 72 20 63 69 70 68 65 72 2e sion for cipher.
41e0: 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 63 69 70 ..[def "[var cip
41f0: 68 65 72 5f 69 73 5f 61 65 61 64 5d 20 5b 61 72 her_is_aead] [ar
4200: 67 20 62 6f 6f 6c 65 61 6e 5d 22 5d 0a 57 68 65 g boolean]"].Whe
4210: 74 68 65 72 20 74 68 65 20 63 69 70 68 65 72 20 ther the cipher
4220: 69 73 20 41 75 74 68 65 6e 74 69 63 61 74 65 64 is Authenticated
4230: 20 45 6e 63 72 79 70 74 69 6f 6e 20 77 69 74 68 Encryption with
4240: 20 41 73 73 6f 63 69 61 74 65 64 20 44 61 74 61 Associated Data
4250: 20 28 41 45 41 44 29 2e 0a 0a 5b 64 65 66 20 22 (AEAD)...[def "
4260: 5b 76 61 72 20 63 69 70 68 65 72 5f 69 64 5d 20 [var cipher_id]
4270: 5b 61 72 67 20 69 64 5d 22 5d 0a 54 68 65 20 4f [arg id]"].The O
4280: 70 65 6e 53 53 4c 20 63 69 70 68 65 72 20 69 64 penSSL cipher id
4290: 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 64 65 ...[def "[var de
42a0: 73 63 72 69 70 74 69 6f 6e 5d 20 5b 61 72 67 20 scription] [arg
42b0: 73 74 72 69 6e 67 5d 22 5d 0a 41 20 74 65 78 74 string]"].A text
42c0: 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 description of
42d0: 74 68 65 20 63 69 70 68 65 72 2e 0a 0a 5b 64 65 the cipher...[de
42e0: 66 20 22 5b 76 61 72 20 68 61 6e 64 73 68 61 6b f "[var handshak
42f0: 65 5f 64 69 67 65 73 74 5d 20 5b 61 72 67 20 62 e_digest] [arg b
4300: 6f 6f 6c 65 61 6e 5d 22 5d 0a 44 69 67 65 73 74 oolean]"].Digest
4310: 20 75 73 65 64 20 64 75 72 69 6e 67 20 68 61 6e used during han
4320: 64 73 68 61 6b 65 2e 0a 0a 5b 6c 69 73 74 5f 65 dshake...[list_e
4330: 6e 64 5d 0a 0a 53 65 73 73 69 6f 6e 20 49 6e 66 nd]..Session Inf
4340: 6f 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e 20 64 o..[list_begin d
4350: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 0a 5b 64 65 efinitions]..[de
4360: 66 20 22 5b 76 61 72 20 61 6c 70 6e 5d 20 5b 61 f "[var alpn] [a
4370: 72 67 20 70 72 6f 74 6f 63 6f 6c 5d 22 5d 0a 54 rg protocol]"].T
4380: 68 65 20 70 72 6f 74 6f 63 6f 6c 20 73 65 6c 65 he protocol sele
4390: 63 74 65 64 20 61 66 74 65 72 20 41 70 70 6c 69 cted after Appli
43a0: 63 61 74 69 6f 6e 2d 4c 61 79 65 72 20 50 72 6f cation-Layer Pro
43b0: 74 6f 63 6f 6c 20 4e 65 67 6f 74 69 61 74 69 6f tocol Negotiatio
43c0: 6e 20 28 41 4c 50 4e 29 2e 0a 0a 5b 64 65 66 20 n (ALPN)...[def
43d0: 22 5b 76 61 72 20 72 65 73 75 6d 61 62 6c 65 5d "[var resumable]
43e0: 20 5b 61 72 67 20 62 6f 6f 6c 65 61 6e 5d 22 5d [arg boolean]"]
43f0: 0a 57 68 65 74 68 65 72 20 74 68 65 20 73 65 73 .Whether the ses
4400: 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 73 75 sion can be resu
4410: 6d 65 64 20 6f 72 20 6e 6f 74 2e 0a 0a 5b 64 65 med or not...[de
4420: 66 20 22 5b 76 61 72 20 73 74 61 72 74 5f 74 69 f "[var start_ti
4430: 6d 65 5d 20 5b 61 72 67 20 73 65 63 6f 6e 64 73 me] [arg seconds
4440: 5d 22 5d 0a 54 69 6d 65 20 73 69 6e 63 65 20 73 ]"].Time since s
4450: 65 73 73 69 6f 6e 20 73 74 61 72 74 65 64 20 69 ession started i
4460: 6e 20 73 65 63 6f 6e 64 73 20 73 69 6e 63 65 20 n seconds since
4470: 65 70 6f 63 68 2e 0a 0a 5b 64 65 66 20 22 5b 76 epoch...[def "[v
4480: 61 72 20 74 69 6d 65 6f 75 74 5d 20 5b 61 72 67 ar timeout] [arg
4490: 20 73 65 63 6f 6e 64 73 5d 22 5d 0a 4d 61 78 20 seconds]"].Max
44a0: 64 75 72 61 74 69 6f 6e 20 6f 66 20 73 65 73 73 duration of sess
44b0: 69 6f 6e 20 69 6e 20 73 65 63 6f 6e 64 73 20 62 ion in seconds b
44c0: 65 66 6f 72 65 20 74 69 6d 65 2d 6f 75 74 2e 0a efore time-out..
44d0: 0a 5b 64 65 66 20 22 5b 76 61 72 20 6c 69 66 65 .[def "[var life
44e0: 74 69 6d 65 5d 20 5b 61 72 67 20 73 65 63 6f 6e time] [arg secon
44f0: 64 73 5d 22 5d 0a 53 65 73 73 69 6f 6e 20 74 69 ds]"].Session ti
4500: 63 6b 65 74 20 6c 69 66 65 74 69 6d 65 20 68 69 cket lifetime hi
4510: 6e 74 20 69 6e 20 73 65 63 6f 6e 64 73 2e 0a 0a nt in seconds...
4520: 5b 64 65 66 20 22 5b 76 61 72 20 73 65 73 73 69 [def "[var sessi
4530: 6f 6e 5f 69 64 5d 20 5b 61 72 67 20 62 69 6e 61 on_id] [arg bina
4540: 72 79 5f 73 74 72 69 6e 67 5d 22 5d 0a 55 6e 69 ry_string]"].Uni
4550: 71 75 65 20 73 65 73 73 69 6f 6e 20 69 64 20 66 que session id f
4560: 6f 72 20 75 73 65 20 69 6e 20 72 65 73 75 6d 69 or use in resumi
4570: 6e 67 20 74 68 65 20 73 65 73 73 69 6f 6e 2e 0a ng the session..
4580: 0a 5b 64 65 66 20 22 5b 76 61 72 20 73 65 73 73 .[def "[var sess
4590: 69 6f 6e 5f 74 69 63 6b 65 74 5d 20 5b 61 72 67 ion_ticket] [arg
45a0: 20 62 69 6e 61 72 79 5f 73 74 72 69 6e 67 5d 22 binary_string]"
45b0: 5d 0a 55 6e 69 71 75 65 20 73 65 73 73 69 6f 6e ].Unique session
45c0: 20 74 69 63 6b 65 74 20 66 6f 72 20 75 73 65 20 ticket for use
45d0: 69 6e 20 72 65 73 75 6d 69 6e 67 20 74 68 65 20 in resuming the
45e0: 73 65 73 73 69 6f 6e 2e 0a 0a 5b 64 65 66 20 22 session...[def "
45f0: 5b 76 61 72 20 74 69 63 6b 65 74 5f 61 70 70 5f [var ticket_app_
4600: 64 61 74 61 5d 20 5b 61 72 67 20 62 69 6e 61 72 data] [arg binar
4610: 79 5f 73 74 72 69 6e 67 5d 22 5d 0a 55 6e 69 71 y_string]"].Uniq
4620: 75 65 20 73 65 73 73 69 6f 6e 20 74 69 63 6b 65 ue session ticke
4630: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 t application da
4640: 74 61 2e 0a 0a 5b 64 65 66 20 22 5b 76 61 72 20 ta...[def "[var
4650: 6d 61 73 74 65 72 5f 6b 65 79 5d 20 5b 61 72 67 master_key] [arg
4660: 20 62 69 6e 61 72 79 5f 73 74 72 69 6e 67 5d 22 binary_string]"
4670: 5d 0a 55 6e 69 71 75 65 20 73 65 73 73 69 6f 6e ].Unique session
4680: 20 6d 61 73 74 65 72 20 6b 65 79 2e 0a 0a 5b 64 master key...[d
4690: 65 66 20 22 5b 76 61 72 20 73 65 73 73 69 6f 6e ef "[var session
46a0: 5f 63 61 63 68 65 5f 6d 6f 64 65 5d 20 5b 61 72 _cache_mode] [ar
46b0: 67 20 6d 6f 64 65 5d 22 5d 0a 53 65 72 76 65 72 g mode]"].Server
46c0: 20 63 61 63 68 65 20 6d 6f 64 65 20 28 63 6c 69 cache mode (cli
46d0: 65 6e 74 2c 20 73 65 72 76 65 72 2c 20 6f 72 20 ent, server, or
46e0: 62 6f 74 68 29 2e 0a 0a 5b 6c 69 73 74 5f 65 6e both)...[list_en
46f0: 64 5d 0a 0a 5b 63 61 6c 6c 20 5b 63 6d 64 20 74 d]..[call [cmd t
4700: 6c 73 3a 3a 63 69 70 68 65 72 73 5d 20 5b 6f 70 ls::ciphers] [op
4710: 74 20 5b 61 72 67 20 70 72 6f 74 6f 63 6f 6c 5d t [arg protocol]
4720: 5d 20 5b 6f 70 74 20 5b 61 72 67 20 76 65 72 62 ] [opt [arg verb
4730: 6f 73 65 5d 5d 20 5b 6f 70 74 20 5b 61 72 67 20 ose]] [opt [arg
4740: 73 75 70 70 6f 72 74 65 64 5d 5d 5d 0a 0a 57 69 supported]]]..Wi
4750: 74 68 6f 75 74 20 61 6e 79 20 61 72 67 73 2c 20 thout any args,
4760: 72 65 74 75 72 6e 73 20 61 20 6c 69 73 74 20 6f returns a list o
4770: 66 20 61 6c 6c 20 73 79 6d 6d 65 74 72 69 63 20 f all symmetric
4780: 63 69 70 68 65 72 73 20 66 6f 72 20 75 73 65 20 ciphers for use
4790: 77 69 74 68 20 74 68 65 0a 5b 61 72 67 20 2d 63 with the.[arg -c
47a0: 69 70 68 65 72 5d 20 6f 70 74 69 6f 6e 2e 20 57 ipher] option. W
47b0: 69 74 68 20 5b 61 72 67 20 70 72 6f 74 6f 63 6f ith [arg protoco
47c0: 6c 5d 2c 20 6f 6e 6c 79 20 74 68 65 20 63 69 70 l], only the cip
47d0: 68 65 72 73 20 73 75 70 70 6f 72 74 65 64 20 66 hers supported f
47e0: 6f 72 20 74 68 61 74 0a 70 72 6f 74 6f 63 6f 6c or that.protocol
47f0: 20 61 72 65 20 72 65 74 75 72 6e 65 64 2e 20 53 are returned. S
4800: 65 65 20 74 68 65 20 5b 63 6d 64 20 74 6c 73 3a ee the [cmd tls:
4810: 3a 70 72 6f 74 6f 63 6f 6c 73 5d 20 63 6f 6d 6d :protocols] comm
4820: 61 6e 64 20 66 6f 72 20 74 68 65 20 73 75 70 70 and for the supp
4830: 6f 72 74 65 64 0a 70 72 6f 74 6f 63 6f 6c 73 2e orted.protocols.
4840: 20 49 66 20 5b 61 72 67 20 76 65 72 62 6f 73 65 If [arg verbose
4850: 5d 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 ] is specified a
4860: 73 20 74 72 75 65 20 74 68 65 6e 20 61 20 76 65 s true then a ve
4870: 72 62 6f 73 65 2c 20 68 75 6d 61 6e 20 72 65 61 rbose, human rea
4880: 64 61 62 6c 65 0a 6c 69 73 74 20 69 73 20 72 65 dable.list is re
4890: 74 75 72 6e 65 64 20 77 69 74 68 20 61 64 64 69 turned with addi
48a0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
48b0: 6f 6e 20 6f 6e 20 74 68 65 20 63 69 70 68 65 72 on on the cipher
48c0: 2e 20 49 66 20 5b 61 72 67 20 73 75 70 70 6f 72 . If [arg suppor
48d0: 74 65 64 5d 0a 69 73 20 73 70 65 63 69 66 69 65 ted].is specifie
48e0: 64 20 61 73 20 74 72 75 65 2c 20 74 68 65 6e 20 d as true, then
48f0: 6f 6e 6c 79 20 74 68 65 20 63 69 70 68 65 72 73 only the ciphers
4900: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 70 supported for p
4910: 72 6f 74 6f 63 6f 6c 20 77 69 6c 6c 20 62 65 20 rotocol will be
4920: 6c 69 73 74 65 64 2e 0a 0a 5b 63 61 6c 6c 20 5b listed...[call [
4930: 63 6d 64 20 74 6c 73 3a 3a 70 72 6f 74 6f 63 6f cmd tls::protoco
4940: 6c 73 5d 5d 0a 0a 52 65 74 75 72 6e 73 20 61 20 ls]]..Returns a
4950: 6c 69 73 74 20 6f 66 20 74 68 65 20 73 75 70 70 list of the supp
4960: 6f 72 74 65 64 20 53 53 4c 2f 54 4c 53 20 70 72 orted SSL/TLS pr
4970: 6f 74 6f 63 6f 6c 73 2e 20 56 61 6c 69 64 20 76 otocols. Valid v
4980: 61 6c 75 65 73 20 61 72 65 3a 0a 5b 63 6f 6e 73 alues are:.[cons
4990: 74 20 73 73 6c 32 5d 2c 20 5b 63 6f 6e 73 74 20 t ssl2], [const
49a0: 73 73 6c 33 5d 2c 20 5b 63 6f 6e 73 74 20 74 6c ssl3], [const tl
49b0: 73 31 5d 2c 20 5b 63 6f 6e 73 74 20 74 6c 73 31 s1], [const tls1
49c0: 2e 31 5d 2c 20 5b 63 6f 6e 73 74 20 74 6c 73 31 .1], [const tls1
49d0: 2e 32 5d 2c 20 61 6e 64 0a 5b 63 6f 6e 73 74 20 .2], and.[const
49e0: 74 6c 73 31 2e 33 5d 2e 20 45 78 61 63 74 20 6c tls1.3]. Exact l
49f0: 69 73 74 20 64 65 70 65 6e 64 73 20 6f 6e 20 4f ist depends on O
4a00: 70 65 6e 53 53 4c 20 76 65 72 73 69 6f 6e 20 61 penSSL version a
4a10: 6e 64 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 nd compile time
4a20: 66 6c 61 67 73 2e 0a 0a 5b 63 61 6c 6c 20 5b 63 flags...[call [c
4a30: 6d 64 20 74 6c 73 3a 3a 76 65 72 73 69 6f 6e 5d md tls::version]
4a40: 5d 0a 0a 52 65 74 75 72 6e 73 20 74 68 65 20 4f ]..Returns the O
4a50: 70 65 6e 53 53 4c 20 76 65 72 73 69 6f 6e 20 73 penSSL version s
4a60: 74 72 69 6e 67 2e 0a 0a 5b 6c 69 73 74 5f 65 6e tring...[list_en
4a70: 64 5d 0a 0a 0a 5b 73 65 63 74 69 6f 6e 20 22 43 d]...[section "C
4a80: 65 72 74 69 66 69 63 61 74 65 20 56 61 6c 69 64 ertificate Valid
4a90: 61 74 69 6f 6e 22 5d 0a 0a 5b 73 75 62 73 65 63 ation"]..[subsec
4aa0: 74 69 6f 6e 20 22 50 4b 49 20 61 6e 64 20 43 65 tion "PKI and Ce
4ab0: 72 74 69 66 69 63 61 74 65 73 22 5d 0a 0a 55 73 rtificates"]..Us
4ac0: 69 6e 67 20 74 68 65 20 50 75 62 6c 69 63 20 4b ing the Public K
4ad0: 65 79 20 49 6e 66 72 61 73 74 72 75 63 74 75 72 ey Infrastructur
4ae0: 65 20 28 50 4b 49 29 2c 20 65 61 63 68 20 75 73 e (PKI), each us
4af0: 65 72 20 63 72 65 61 74 65 73 20 61 20 70 72 69 er creates a pri
4b00: 76 61 74 65 20 6b 65 79 20 74 68 61 74 0a 6f 6e vate key that.on
4b10: 6c 79 20 74 68 65 79 20 6b 6e 6f 77 20 61 62 6f ly they know abo
4b20: 75 74 20 61 6e 64 20 61 20 70 75 62 6c 69 63 20 ut and a public
4b30: 6b 65 79 20 74 68 65 79 20 63 61 6e 20 65 78 63 key they can exc
4b40: 68 61 6e 67 65 20 77 69 74 68 20 6f 74 68 65 72 hange with other
4b50: 73 20 66 6f 72 20 75 73 65 20 69 6e 0a 65 6e 63 s for use in.enc
4b60: 72 79 70 74 69 6e 67 20 61 6e 64 20 64 65 63 72 rypting and decr
4b70: 79 70 74 69 6e 67 20 64 61 74 61 2e 20 54 68 65 ypting data. The
4b80: 20 70 72 6f 63 65 73 73 20 69 73 20 74 68 65 20 process is the
4b90: 73 65 6e 64 65 72 20 65 6e 63 72 79 70 74 73 20 sender encrypts
4ba0: 74 68 65 69 72 20 64 61 74 61 0a 75 73 69 6e 67 their data.using
4bb0: 20 74 68 65 69 72 20 70 72 69 76 61 74 65 20 6b their private k
4bc0: 65 79 20 61 6e 64 20 74 68 65 20 72 65 63 65 69 ey and the recei
4bd0: 76 65 72 27 73 20 70 75 62 6c 69 63 20 6b 65 79 ver's public key
4be0: 2e 20 54 68 65 20 64 61 74 61 20 69 73 20 74 68 . The data is th
4bf0: 65 6e 20 73 65 6e 74 0a 74 6f 20 74 68 65 20 72 en sent.to the r
4c00: 65 63 65 69 76 65 72 2e 20 49 6e 20 61 20 73 69 eceiver. In a si
4c10: 6d 69 6c 61 72 20 6d 61 6e 6e 65 72 2c 20 74 68 milar manner, th
4c20: 65 20 72 65 63 65 69 76 65 72 20 75 73 65 73 20 e receiver uses
4c30: 74 68 65 69 72 20 70 72 69 76 61 74 65 20 6b 65 their private ke
4c40: 79 20 61 6e 64 0a 74 68 65 20 73 65 6e 64 65 72 y and.the sender
4c50: 27 73 20 70 75 62 6c 69 63 20 6b 65 79 20 74 6f 's public key to
4c60: 20 64 65 63 72 79 70 74 20 74 68 65 20 64 61 74 decrypt the dat
4c70: 61 2e 20 54 68 69 73 20 70 72 6f 76 69 64 65 73 a. This provides
4c80: 20 64 61 74 61 20 69 6e 74 65 67 72 69 74 79 2c data integrity,
4c90: 20 74 6f 0a 65 6e 73 75 72 65 20 74 68 65 20 64 to.ensure the d
4ca0: 61 74 61 20 63 61 6e 27 74 20 62 65 20 76 69 65 ata can't be vie
4cb0: 77 65 64 20 6f 72 20 61 6c 74 65 72 65 64 20 64 wed or altered d
4cc0: 75 72 69 6e 67 20 74 72 61 6e 73 70 6f 72 74 2e uring transport.
4cd0: 20 53 65 65 20 74 68 65 0a 5b 6f 70 74 69 6f 6e See the.[option
4ce0: 20 2d 6b 65 79 5d 20 61 6e 64 20 5b 6f 70 74 69 -key] and [opti
4cf0: 6f 6e 20 2d 6b 65 79 66 69 6c 65 5d 20 6f 70 74 on -keyfile] opt
4d00: 69 6f 6e 73 20 66 6f 72 20 68 6f 77 20 74 6f 20 ions for how to
4d10: 73 70 65 63 69 66 79 20 74 68 65 20 70 72 69 76 specify the priv
4d20: 61 74 65 20 6b 65 79 2e 0a 41 6c 73 6f 20 73 65 ate key..Also se
4d30: 65 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 70 e the [option -p
4d40: 61 73 73 77 6f 72 64 5d 20 6f 70 74 69 6f 6e 20 assword] option
4d50: 66 6f 72 20 68 6f 77 20 74 6f 20 70 72 6f 76 69 for how to provi
4d60: 64 65 20 74 68 65 20 70 61 73 73 77 6f 72 64 2e de the password.
4d70: 0a 5b 70 61 72 61 5d 0a 49 6e 20 6f 72 64 65 72 .[para].In order
4d80: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 75 74 68 to provide auth
4d90: 65 6e 74 69 63 61 74 69 6f 6e 2c 20 69 2e 65 2e entication, i.e.
4da0: 20 65 6e 73 75 72 69 6e 67 20 73 6f 6d 65 6f 6e ensuring someon
4db0: 65 20 69 73 20 77 68 6f 20 74 68 65 79 20 73 61 e is who they sa
4dc0: 79 20 74 68 65 79 0a 61 72 65 2c 20 74 68 65 20 y they.are, the
4dd0: 70 75 62 6c 69 63 20 6b 65 79 20 61 6e 64 20 75 public key and u
4de0: 73 65 72 20 69 64 65 6e 74 69 66 69 63 61 74 69 ser identificati
4df0: 6f 6e 20 69 6e 66 6f 20 69 73 20 73 74 6f 72 65 on info is store
4e00: 64 20 69 6e 20 61 20 58 2e 35 30 39 0a 63 65 72 d in a X.509.cer
4e10: 74 69 66 69 63 61 74 65 20 61 6e 64 20 74 68 61 tificate and tha
4e20: 74 20 63 65 72 74 69 66 69 63 61 74 65 20 69 73 t certificate is
4e30: 20 61 75 74 68 65 6e 74 69 63 61 74 65 64 20 28 authenticated (
4e40: 69 2e 65 2e 20 73 69 67 6e 65 64 29 20 62 79 20 i.e. signed) by
4e50: 61 20 43 65 72 74 69 66 69 63 61 74 65 0a 41 75 a Certificate.Au
4e60: 74 68 6f 72 69 74 79 20 28 43 41 29 2e 20 55 73 thority (CA). Us
4e70: 65 72 73 20 63 61 6e 20 74 68 65 6e 20 65 78 63 ers can then exc
4e80: 68 61 6e 67 65 20 74 68 65 73 65 20 63 65 72 74 hange these cert
4e90: 69 66 69 63 61 74 65 73 20 64 75 72 69 6e 67 20 ificates during
4ea0: 74 68 65 20 54 4c 53 0a 69 6e 69 74 69 61 6c 69 the TLS.initiali
4eb0: 7a 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 20 61 zation process a
4ec0: 6e 64 20 63 68 65 63 6b 20 74 68 65 6d 20 61 67 nd check them ag
4ed0: 61 69 6e 73 74 20 74 68 65 20 72 6f 6f 74 20 43 ainst the root C
4ee0: 41 20 63 65 72 74 69 66 69 63 61 74 65 73 20 74 A certificates t
4ef0: 6f 20 65 6e 73 75 72 65 0a 74 68 65 79 20 61 72 o ensure.they ar
4f00: 65 20 76 61 6c 69 64 2e 20 54 68 69 73 20 69 73 e valid. This is
4f10: 20 68 61 6e 64 6c 65 64 20 62 79 20 4f 70 65 6e handled by Open
4f20: 53 53 4c 20 76 69 61 20 74 68 65 20 5b 6f 70 74 SSL via the [opt
4f30: 69 6f 6e 20 2d 72 65 71 75 65 73 74 5d 20 61 6e ion -request] an
4f40: 64 0a 5b 6f 70 74 69 6f 6e 20 2d 72 65 71 75 69 d.[option -requi
4f50: 72 65 5d 20 6f 70 74 69 6f 6e 73 2e 20 53 65 65 re] options. See
4f60: 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 63 61 the [option -ca
4f70: 64 69 72 5d 2c 20 5b 6f 70 74 69 6f 6e 20 2d 63 dir], [option -c
4f80: 61 64 69 72 5d 2c 20 61 6e 64 0a 5b 6f 70 74 69 adir], and.[opti
4f90: 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f 70 74 on -castore] opt
4fa0: 69 6f 6e 73 20 66 6f 72 20 68 6f 77 20 74 70 20 ions for how tp
4fb0: 73 70 65 63 69 66 79 20 77 68 65 72 65 20 74 6f specify where to
4fc0: 20 66 69 6e 64 20 74 68 65 20 43 41 20 63 65 72 find the CA cer
4fd0: 74 69 66 69 63 61 74 65 73 2e 0a 4f 70 74 69 6f tificates..Optio
4fe0: 6e 61 6c 6c 79 2c 20 69 6e 20 61 20 66 75 74 75 nally, in a futu
4ff0: 72 65 20 72 65 6c 65 61 73 65 2c 20 74 68 65 79 re release, they
5000: 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 63 68 65 can also be che
5010: 63 6b 65 64 20 61 67 61 69 6e 73 74 20 74 68 65 cked against the
5020: 20 43 65 72 74 69 66 69 63 61 74 65 0a 52 65 76 Certificate.Rev
5030: 6f 63 61 74 69 6f 6e 20 4c 69 73 74 20 28 43 52 ocation List (CR
5040: 4c 29 20 6f 66 20 72 65 76 6f 6b 65 64 20 63 65 L) of revoked ce
5050: 72 74 69 66 69 63 61 74 65 73 2e 20 43 65 72 74 rtificates. Cert
5060: 69 66 69 63 61 74 65 73 20 63 61 6e 20 61 6c 73 ificates can als
5070: 6f 20 62 65 0a 73 65 6c 66 2d 73 69 67 6e 65 64 o be.self-signed
5080: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 20 62 , but they are b
5090: 79 20 64 65 66 61 75 6c 74 20 6e 6f 74 20 74 72 y default not tr
50a0: 75 73 74 65 64 20 75 6e 6c 65 73 73 20 79 6f 75 usted unless you
50b0: 20 61 64 64 20 74 68 65 6d 20 74 6f 20 79 6f 75 add them to you
50c0: 72 0a 63 65 72 74 69 66 69 63 61 74 65 20 73 74 r.certificate st
50d0: 6f 72 65 2e 0a 5b 70 61 72 61 5d 0a 54 79 70 69 ore..[para].Typi
50e0: 63 61 6c 6c 79 20 77 68 65 6e 20 76 69 73 69 74 cally when visit
50f0: 69 6e 67 20 77 65 62 20 73 69 74 65 73 2c 20 6f ing web sites, o
5100: 6e 6c 79 20 74 68 65 20 63 6c 69 65 6e 74 20 6e nly the client n
5110: 65 65 64 73 20 74 6f 20 63 68 65 63 6b 20 74 68 eeds to check th
5120: 65 20 73 65 72 76 65 72 27 73 0a 63 65 72 74 69 e server's.certi
5130: 66 69 63 61 74 65 20 74 6f 20 65 6e 73 75 72 65 ficate to ensure
5140: 20 69 74 20 69 73 20 76 61 6c 69 64 2e 20 54 68 it is valid. Th
5150: 65 20 73 65 72 76 65 72 20 64 6f 65 73 6e 27 74 e server doesn't
5160: 20 6e 65 65 64 20 74 6f 20 63 68 65 63 6b 20 74 need to check t
5170: 68 65 20 63 6c 69 65 6e 74 0a 63 65 72 74 69 66 he client.certif
5180: 69 63 61 74 65 20 75 6e 6c 65 73 73 20 79 6f 75 icate unless you
5190: 20 6e 65 65 64 20 74 6f 20 61 75 74 68 65 6e 74 need to authent
51a0: 69 63 61 74 65 20 77 69 74 68 20 74 68 65 6d 20 icate with them
51b0: 74 6f 20 6c 6f 67 69 6e 2c 20 65 74 63 2e 20 53 to login, etc. S
51c0: 65 65 20 74 68 65 0a 5b 6f 70 74 69 6f 6e 20 2d ee the.[option -
51d0: 63 65 72 74 5d 20 61 6e 64 20 5b 6f 70 74 69 6f cert] and [optio
51e0: 6e 20 2d 63 65 72 74 66 69 6c 65 5d 20 6f 70 74 n -certfile] opt
51f0: 69 6f 6e 73 20 69 66 20 79 6f 75 20 6e 65 65 64 ions if you need
5200: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 65 to provide a ce
5210: 72 74 69 66 69 63 61 74 65 2e 0a 0a 0a 5b 73 75 rtificate....[su
5220: 62 73 65 63 74 69 6f 6e 20 22 53 75 6d 6d 61 72 bsection "Summar
5230: 79 20 6f 66 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e y of command lin
5240: 65 20 6f 70 74 69 6f 6e 73 22 5d 0a 0a 54 68 65 e options"]..The
5250: 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 74 69 6f following optio
5260: 6e 73 20 61 72 65 20 75 73 65 64 20 66 6f 72 20 ns are used for
5270: 70 65 65 72 20 63 65 72 74 69 66 69 63 61 74 65 peer certificate
5280: 20 76 61 6c 69 64 61 74 69 6f 6e 3a 0a 0a 5b 6c validation:..[l
5290: 69 73 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f 6e ist_begin option
52a0: 73 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 61 s]..[opt_def -ca
52b0: 64 69 72 20 5b 61 72 67 20 64 69 72 65 63 74 6f dir [arg directo
52c0: 72 79 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 ry]].Specifies t
52d0: 68 65 20 64 69 72 65 63 74 6f 72 79 20 77 68 65 he directory whe
52e0: 72 65 20 74 68 65 20 43 65 72 74 69 66 69 63 61 re the Certifica
52f0: 74 65 20 41 75 74 68 6f 72 69 74 79 20 28 43 41 te Authority (CA
5300: 29 20 63 65 72 74 69 66 69 63 61 74 65 73 20 61 ) certificates a
5310: 72 65 0a 73 74 6f 72 65 64 2e 20 54 68 65 20 64 re.stored. The d
5320: 65 66 61 75 6c 74 20 69 73 20 70 6c 61 74 66 6f efault is platfo
5330: 72 6d 20 73 70 65 63 69 66 69 63 2c 20 62 75 74 rm specific, but
5340: 20 69 73 20 75 73 75 61 6c 6c 79 20 5b 66 69 6c is usually [fil
5350: 65 20 22 2f 65 74 63 2f 73 73 6c 2f 63 65 72 74 e "/etc/ssl/cert
5360: 73 22 5d 20 6f 6e 0a 4c 69 6e 75 78 2f 55 6e 69 s"] on.Linux/Uni
5370: 78 20 73 79 73 74 65 6d 73 2e 20 54 68 65 20 64 x systems. The d
5380: 65 66 61 75 6c 74 20 6c 6f 63 61 74 69 6f 6e 20 efault location
5390: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
53a0: 6e 20 62 79 20 74 68 65 0a 5b 76 61 72 20 53 53 n by the.[var SS
53b0: 4c 5f 43 45 52 54 5f 44 49 52 5d 20 65 6e 76 69 L_CERT_DIR] envi
53c0: 72 6f 6e 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 ronment variable
53d0: 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 63 61 66 ...[opt_def -caf
53e0: 69 6c 65 20 5b 61 72 67 20 66 69 6c 65 6e 61 6d ile [arg filenam
53f0: 65 5d 5d 0a 53 70 65 63 69 66 69 65 73 20 74 68 e]].Specifies th
5400: 65 20 66 69 6c 65 20 77 69 74 68 20 74 68 65 20 e file with the
5410: 43 65 72 74 69 66 69 63 61 74 65 20 41 75 74 68 Certificate Auth
5420: 6f 72 69 74 79 20 28 43 41 29 20 63 65 72 74 69 ority (CA) certi
5430: 66 69 63 61 74 65 73 20 74 6f 20 75 73 65 20 69 ficates to use i
5440: 6e 0a 5b 63 6f 6e 73 74 20 50 45 4d 5d 20 66 69 n.[const PEM] fi
5450: 6c 65 20 66 6f 72 6d 61 74 2e 20 54 68 65 20 64 le format. The d
5460: 65 66 61 75 6c 74 20 69 73 20 5b 66 69 6c 65 20 efault is [file
5470: 63 65 72 74 2e 70 65 6d 5d 2c 20 69 6e 20 74 68 cert.pem], in th
5480: 65 20 4f 70 65 6e 53 53 4c 0a 64 69 72 65 63 74 e OpenSSL.direct
5490: 6f 72 79 2e 20 4f 6e 20 4c 69 6e 75 78 2f 55 6e ory. On Linux/Un
54a0: 69 78 20 73 79 73 74 65 6d 73 2c 20 74 68 69 73 ix systems, this
54b0: 20 69 73 20 75 73 75 61 6c 6c 79 20 5b 66 69 6c is usually [fil
54c0: 65 20 2f 65 74 63 2f 73 73 6c 2f 63 61 2d 62 75 e /etc/ssl/ca-bu
54d0: 6e 64 6c 65 2e 70 65 6d 5d 2e 0a 54 68 65 20 64 ndle.pem]..The d
54e0: 65 66 61 75 6c 74 20 66 69 6c 65 20 63 61 6e 20 efault file can
54f0: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 be overridden by
5500: 20 74 68 65 20 5b 76 61 72 20 53 53 4c 5f 43 45 the [var SSL_CE
5510: 52 54 5f 46 49 4c 45 5d 20 65 6e 76 69 72 6f 6e RT_FILE] environ
5520: 6d 65 6e 74 0a 76 61 72 69 61 62 6c 65 2e 0a 0a ment.variable...
5530: 5b 6f 70 74 5f 64 65 66 20 2d 63 61 73 74 6f 72 [opt_def -castor
5540: 65 20 5b 61 72 67 20 55 52 49 5d 5d 0a 53 70 65 e [arg URI]].Spe
5550: 63 69 66 69 65 73 20 74 68 65 20 55 6e 69 66 6f cifies the Unifo
5560: 72 6d 20 52 65 73 6f 75 72 63 65 20 49 64 65 6e rm Resource Iden
5570: 74 69 66 69 65 72 20 28 55 52 49 29 20 66 6f 72 tifier (URI) for
5580: 20 74 68 65 20 43 65 72 74 69 66 69 63 61 74 65 the Certificate
5590: 20 41 75 74 68 6f 72 69 74 79 0a 28 43 41 29 20 Authority.(CA)
55a0: 73 74 6f 72 65 2c 20 77 68 69 63 68 20 6d 61 79 store, which may
55b0: 20 62 65 20 61 20 73 69 6e 67 6c 65 20 63 6f 6e be a single con
55c0: 74 61 69 6e 65 72 20 6f 72 20 61 20 63 61 74 61 tainer or a cata
55d0: 6c 6f 67 20 6f 66 20 63 6f 6e 74 61 69 6e 65 72 log of container
55e0: 73 2e 0a 53 74 61 72 74 69 6e 67 20 77 69 74 68 s..Starting with
55f0: 20 4f 70 65 6e 53 53 4c 20 33 2e 32 20 6f 6e 20 OpenSSL 3.2 on
5600: 4d 53 20 57 69 6e 64 6f 77 73 2c 20 73 65 74 20 MS Windows, set
5610: 74 6f 20 22 5b 63 6f 6e 73 74 20 22 6f 72 67 2e to "[const "org.
5620: 6f 70 65 6e 73 73 6c 2e 77 69 6e 73 74 6f 72 65 openssl.winstore
5630: 3a 2f 2f 22 5d 22 0a 74 6f 20 75 73 65 20 74 68 ://"]".to use th
5640: 65 20 62 75 69 6c 74 2d 69 6e 20 4d 53 20 57 69 e built-in MS Wi
5650: 6e 64 6f 77 73 20 43 65 72 74 69 66 69 63 61 74 ndows Certificat
5660: 65 20 53 74 6f 72 65 2e 0a 54 68 69 73 20 73 74 e Store..This st
5670: 6f 72 65 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 ore only support
5680: 73 20 72 6f 6f 74 20 63 65 72 74 69 66 69 63 61 s root certifica
5690: 74 65 20 73 74 6f 72 65 73 2e 20 53 65 65 0a 5b te stores. See.[
56a0: 73 65 63 74 72 65 66 20 22 43 65 72 74 69 66 69 sectref "Certifi
56b0: 63 61 74 65 20 56 61 6c 69 64 61 74 69 6f 6e 22 cate Validation"
56c0: 5d 20 66 6f 72 20 6d 6f 72 65 20 64 65 74 61 69 ] for more detai
56d0: 6c 73 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 72 ls...[opt_def -r
56e0: 65 71 75 65 73 74 20 5b 61 72 67 20 62 6f 6f 6c equest [arg bool
56f0: 5d 5d 0a 52 65 71 75 65 73 74 20 61 20 63 65 72 ]].Request a cer
5700: 74 69 66 69 63 61 74 65 20 66 72 6f 6d 20 74 68 tificate from th
5710: 65 20 70 65 65 72 20 64 75 72 69 6e 67 20 74 68 e peer during th
5720: 65 20 53 53 4c 20 68 61 6e 64 73 68 61 6b 65 2e e SSL handshake.
5730: 20 54 68 69 73 20 69 73 20 6e 65 65 64 65 64 0a This is needed.
5740: 74 6f 20 64 6f 20 43 65 72 74 69 66 69 63 61 74 to do Certificat
5750: 65 20 56 61 6c 69 64 61 74 69 6f 6e 2e 20 53 74 e Validation. St
5760: 61 72 74 69 6e 67 20 69 6e 20 54 63 6c 54 4c 53 arting in TclTLS
5770: 20 31 2e 38 2c 20 74 68 65 20 64 65 66 61 75 6c 1.8, the defaul
5780: 74 20 69 73 0a 5b 63 6f 6e 73 74 20 74 72 75 65 t is.[const true
5790: 5d 2e 20 53 74 61 72 74 69 6e 67 20 69 6e 20 54 ]. Starting in T
57a0: 63 6c 54 4c 53 20 32 2e 30 2c 20 49 66 20 73 65 clTLS 2.0, If se
57b0: 74 20 74 6f 20 5b 63 6f 6e 73 74 20 66 61 6c 73 t to [const fals
57c0: 65 5d 20 61 6e 64 0a 5b 6f 70 74 69 6f 6e 20 2d e] and.[option -
57d0: 72 65 71 75 69 72 65 5d 20 69 73 20 5b 63 6f 6e require] is [con
57e0: 73 74 20 74 72 75 65 5d 2c 20 74 68 65 6e 20 74 st true], then t
57f0: 68 69 73 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 his will be over
5800: 72 69 64 64 65 6e 20 74 6f 20 5b 63 6f 6e 73 74 ridden to [const
5810: 20 74 72 75 65 5d 2e 0a 49 6e 20 61 64 64 69 74 true]..In addit
5820: 69 6f 6e 2c 20 74 68 65 20 63 6c 69 65 6e 74 20 ion, the client
5830: 63 61 6e 20 6d 61 6e 75 61 6c 6c 79 20 69 6e 73 can manually ins
5840: 70 65 63 74 20 61 6e 64 20 61 63 63 65 70 74 20 pect and accept
5850: 6f 72 20 72 65 6a 65 63 74 0a 65 61 63 68 20 63 or reject.each c
5860: 65 72 74 69 66 69 63 61 74 65 20 75 73 69 6e 67 ertificate using
5870: 20 74 68 65 20 5b 61 72 67 20 2d 76 61 6c 69 64 the [arg -valid
5880: 61 74 65 63 6f 6d 6d 61 6e 64 5d 20 6f 70 74 69 atecommand] opti
5890: 6f 6e 2e 0a 0a 5b 6f 70 74 5f 64 65 66 20 2d 72 on...[opt_def -r
58a0: 65 71 75 69 72 65 20 5b 61 72 67 20 62 6f 6f 6c equire [arg bool
58b0: 5d 5d 0a 52 65 71 75 69 72 65 20 61 20 76 61 6c ]].Require a val
58c0: 69 64 20 63 65 72 74 69 66 69 63 61 74 65 20 66 id certificate f
58d0: 72 6f 6d 20 74 68 65 20 70 65 65 72 20 64 75 72 rom the peer dur
58e0: 69 6e 67 20 74 68 65 20 53 53 4c 20 68 61 6e 64 ing the SSL hand
58f0: 73 68 61 6b 65 2e 20 49 66 20 74 68 69 73 20 69 shake. If this i
5900: 73 0a 73 65 74 20 74 6f 20 74 72 75 65 2c 20 74 s.set to true, t
5910: 68 65 6e 20 5b 6f 70 74 69 6f 6e 20 2d 72 65 71 hen [option -req
5920: 75 65 73 74 5d 20 6d 75 73 74 20 61 6c 73 6f 20 uest] must also
5930: 62 65 20 73 65 74 20 74 6f 20 74 72 75 65 20 61 be set to true a
5940: 6e 64 20 61 20 65 69 74 68 65 72 0a 5b 6f 70 74 nd a either.[opt
5950: 69 6f 6e 20 2d 63 61 64 69 72 5d 2c 20 5b 6f 70 ion -cadir], [op
5960: 74 69 6f 6e 20 2d 63 61 66 69 6c 65 5d 2c 20 5b tion -cafile], [
5970: 6f 70 74 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d option -castore]
5980: 2c 20 6f 72 20 61 20 70 6c 61 74 66 6f 72 6d 20 , or a platform
5990: 64 65 66 61 75 6c 74 0a 6d 75 73 74 20 62 65 20 default.must be
59a0: 70 72 6f 76 69 64 65 64 20 69 6e 20 6f 72 64 65 provided in orde
59b0: 72 20 74 6f 20 76 61 6c 69 64 61 74 65 20 61 67 r to validate ag
59c0: 61 69 6e 73 74 2e 20 54 68 65 20 64 65 66 61 75 ainst. The defau
59d0: 6c 74 20 69 6e 20 54 63 6c 54 4c 53 20 31 2e 38 lt in TclTLS 1.8
59e0: 20 61 6e 64 0a 65 61 72 6c 69 65 72 20 76 65 72 and.earlier ver
59f0: 73 69 6f 6e 73 20 69 73 20 5b 63 6f 6e 73 74 20 sions is [const
5a00: 66 61 6c 73 65 5d 20 73 69 6e 63 65 20 6e 6f 74 false] since not
5a10: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 20 68 all platforms h
5a20: 61 76 65 20 63 65 72 74 69 66 69 63 61 74 65 73 ave certificates
5a30: 20 74 6f 0a 76 61 6c 69 64 61 74 65 20 61 67 61 to.validate aga
5a40: 69 6e 73 74 20 69 6e 20 61 20 66 6f 72 6d 20 63 inst in a form c
5a50: 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68 20 4f ompatible with O
5a60: 70 65 6e 53 53 4c 2e 20 53 74 61 72 74 69 6e 67 penSSL. Starting
5a70: 20 69 6e 20 54 63 6c 54 4c 53 20 32 2e 30 2c 0a in TclTLS 2.0,.
5a80: 74 68 65 20 64 65 66 61 75 6c 74 20 69 73 20 5b the default is [
5a90: 63 6f 6e 73 74 20 74 72 75 65 5d 2e 0a 0a 5b 6c const true]...[l
5aa0: 69 73 74 5f 65 6e 64 5d 0a 0a 5b 73 75 62 73 65 ist_end]..[subse
5ab0: 63 74 69 6f 6e 20 22 57 68 65 6e 20 61 72 65 20 ction "When are
5ac0: 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 20 6f 70 74 command line opt
5ad0: 69 6f 6e 73 20 6e 65 65 64 65 64 3f 22 5d 0a 0a ions needed?"]..
5ae0: 49 6e 20 54 63 6c 54 4c 53 20 31 2e 38 20 61 6e In TclTLS 1.8 an
5af0: 64 20 65 61 72 6c 69 65 72 20 76 65 72 73 69 6f d earlier versio
5b00: 6e 73 2c 20 63 65 72 74 69 66 69 63 61 74 65 20 ns, certificate
5b10: 76 61 6c 69 64 61 74 69 6f 6e 20 69 73 0a 5b 65 validation is.[e
5b20: 6d 70 68 20 4e 4f 54 5d 20 65 6e 61 62 6c 65 64 mph NOT] enabled
5b30: 20 62 79 20 64 65 66 61 75 6c 74 2e 20 54 68 69 by default. Thi
5b40: 73 20 6c 69 6d 69 74 61 74 69 6f 6e 20 69 73 20 s limitation is
5b50: 64 75 65 20 74 6f 20 74 68 65 20 6c 61 63 6b 20 due to the lack
5b60: 6f 66 20 61 20 63 6f 6d 6d 6f 6e 0a 63 72 6f 73 of a common.cros
5b70: 73 20 70 6c 61 74 66 6f 72 6d 20 64 61 74 61 62 s platform datab
5b80: 61 73 65 20 6f 66 20 43 65 72 74 69 66 69 63 61 ase of Certifica
5b90: 74 65 20 41 75 74 68 6f 72 69 74 79 20 28 43 41 te Authority (CA
5ba0: 29 20 70 72 6f 76 69 64 65 64 20 63 65 72 74 69 ) provided certi
5bb0: 66 69 63 61 74 65 73 20 74 6f 0a 76 61 6c 69 64 ficates to.valid
5bc0: 61 74 65 20 61 67 61 69 6e 73 74 2e 20 4d 61 6e ate against. Man
5bd0: 79 20 4c 69 6e 75 78 20 73 79 73 74 65 6d 73 20 y Linux systems
5be0: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 natively support
5bf0: 20 4f 70 65 6e 53 53 4c 20 61 6e 64 20 74 68 75 OpenSSL and thu
5c00: 73 20 68 61 76 65 0a 74 68 65 73 65 20 63 65 72 s have.these cer
5c10: 74 69 66 69 63 61 74 65 73 20 69 6e 73 74 61 6c tificates instal
5c20: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 led as part of t
5c30: 68 65 20 4f 53 2c 20 62 75 74 20 4d 61 63 4f 53 he OS, but MacOS
5c40: 20 61 6e 64 20 4d 53 20 57 69 6e 64 6f 77 73 20 and MS Windows
5c50: 64 6f 20 6e 6f 74 2e 0a 53 74 61 72 69 6e 67 20 do not..Staring
5c60: 69 6e 20 54 63 6c 54 4c 53 20 32 2e 30 2c 20 74 in TclTLS 2.0, t
5c70: 68 69 73 20 68 61 73 20 62 65 65 6e 20 63 68 61 his has been cha
5c80: 6e 67 65 64 20 74 6f 20 72 65 71 75 69 72 65 20 nged to require
5c90: 63 65 72 74 69 66 69 63 61 74 65 20 76 61 6c 69 certificate vali
5ca0: 64 61 74 69 6f 6e 0a 62 79 20 64 65 66 61 75 6c dation.by defaul
5cb0: 74 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 75 t. In order to u
5cc0: 73 65 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d se the [option -
5cd0: 72 65 71 75 69 72 65 5d 20 6f 70 74 69 6f 6e 2c require] option,
5ce0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
5cf0: 6f 77 69 6e 67 0a 6d 75 73 74 20 62 65 20 74 72 owing.must be tr
5d00: 75 65 3a 0a 0a 5b 6c 69 73 74 5f 62 65 67 69 6e ue:..[list_begin
5d10: 20 69 74 65 6d 69 7a 65 64 5d 0a 0a 5b 69 74 65 itemized]..[ite
5d20: 6d 5d 0a 4f 6e 20 4c 69 6e 75 78 20 61 6e 64 20 m].On Linux and
5d30: 55 6e 69 78 20 73 79 73 74 65 6d 73 20 77 69 74 Unix systems wit
5d40: 68 20 4f 70 65 6e 53 53 4c 20 61 6c 72 65 61 64 h OpenSSL alread
5d50: 79 20 69 6e 73 74 61 6c 6c 65 64 20 6f 72 20 69 y installed or i
5d60: 66 20 74 68 65 20 43 41 0a 63 65 72 74 69 66 69 f the CA.certifi
5d70: 63 61 74 65 73 20 61 72 65 20 61 76 61 69 6c 61 cates are availa
5d80: 62 6c 65 20 69 6e 20 50 45 4d 20 66 6f 72 6d 61 ble in PEM forma
5d90: 74 2c 20 61 6e 64 20 69 66 20 74 68 65 79 20 61 t, and if they a
5da0: 72 65 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 re stored in the
5db0: 0a 73 74 61 6e 64 61 72 64 20 6c 6f 63 61 74 69 .standard locati
5dc0: 6f 6e 73 2c 20 6f 72 20 69 66 20 74 68 65 20 5b ons, or if the [
5dd0: 76 61 72 20 53 53 4c 5f 43 45 52 54 5f 44 49 52 var SSL_CERT_DIR
5de0: 5d 20 6f 72 20 5b 76 61 72 20 53 53 4c 5f 43 45 ] or [var SSL_CE
5df0: 52 54 5f 46 49 4c 45 5d 0a 65 6e 76 69 72 6f 6e RT_FILE].environ
5e00: 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 61 ment variables a
5e10: 72 65 20 73 65 74 2c 20 74 68 65 6e 20 5b 6f 70 re set, then [op
5e20: 74 69 6f 6e 20 2d 63 61 64 69 72 5d 2c 20 5b 6f tion -cadir], [o
5e30: 70 74 69 6f 6e 20 2d 63 61 64 69 72 5d 2c 0a 61 ption -cadir],.a
5e40: 6e 64 20 5b 6f 70 74 69 6f 6e 20 2d 63 61 73 74 nd [option -cast
5e50: 6f 72 65 5d 20 61 72 65 6e 27 74 20 6e 65 65 64 ore] aren't need
5e60: 65 64 2e 0a 0a 5b 69 74 65 6d 5d 0a 49 66 20 4f ed...[item].If O
5e70: 70 65 6e 53 53 4c 20 69 73 20 6e 6f 74 20 69 6e penSSL is not in
5e80: 73 74 61 6c 6c 65 64 20 69 6e 20 74 68 65 20 64 stalled in the d
5e90: 65 66 61 75 6c 74 20 6c 6f 63 61 74 69 6f 6e 2c efault location,
5ea0: 20 6f 72 20 77 68 65 6e 20 75 73 69 6e 67 20 4d or when using M
5eb0: 61 63 20 4f 53 0a 6f 72 20 4d 53 20 57 69 6e 64 ac OS.or MS Wind
5ec0: 6f 77 73 20 61 6e 64 20 4f 70 65 6e 53 53 4c 20 ows and OpenSSL
5ed0: 69 73 20 69 6e 73 74 61 6c 6c 65 64 2c 20 74 68 is installed, th
5ee0: 65 20 5b 76 61 72 20 53 53 4c 5f 43 45 52 54 5f e [var SSL_CERT_
5ef0: 44 49 52 5d 20 61 6e 64 2f 6f 72 0a 5b 76 61 72 DIR] and/or.[var
5f00: 20 53 53 4c 5f 43 45 52 54 5f 46 49 4c 45 5d 20 SSL_CERT_FILE]
5f10: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 76 61 72 69 environment vari
5f20: 61 62 6c 65 73 20 6f 72 20 74 68 65 20 6f 6e 65 ables or the one
5f30: 20 6f 66 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 of the [option
5f40: 2d 63 61 64 69 72 5d 2c 0a 5b 6f 70 74 69 6f 6e -cadir],.[option
5f50: 20 2d 63 61 64 69 72 5d 2c 20 6f 72 20 5b 6f 70 -cadir], or [op
5f60: 74 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f tion -castore] o
5f70: 70 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 64 ptions must be d
5f80: 65 66 69 6e 65 64 2e 0a 0a 5b 69 74 65 6d 5d 0a efined...[item].
5f90: 4f 6e 20 4d 53 20 57 69 6e 64 6f 77 73 2c 20 73 On MS Windows, s
5fa0: 74 61 72 74 69 6e 67 20 69 6e 20 4f 70 65 6e 53 tarting in OpenS
5fb0: 53 4c 20 33 2e 32 2c 20 69 74 20 69 73 20 6e 6f SL 3.2, it is no
5fc0: 77 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 61 63 w possible to ac
5fd0: 63 65 73 73 20 74 68 65 0a 62 75 69 6c 74 2d 69 cess the.built-i
5fe0: 6e 20 57 69 6e 64 6f 77 73 20 43 65 72 74 69 66 n Windows Certif
5ff0: 69 63 61 74 65 20 53 74 6f 72 65 20 66 72 6f 6d icate Store from
6000: 20 4f 70 65 6e 53 53 4c 2e 20 54 68 69 73 20 63 OpenSSL. This c
6010: 61 6e 20 75 74 69 6c 69 7a 65 64 20 62 79 0a 73 an utilized by.s
6020: 65 74 74 69 6e 67 20 74 68 65 20 5b 6f 70 74 69 etting the [opti
6030: 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f 70 74 on -castore] opt
6040: 69 6f 6e 20 74 6f 20 22 5b 63 6f 6e 73 74 20 6f ion to "[const o
6050: 72 67 2e 6f 70 65 6e 73 73 6c 2e 77 69 6e 73 74 rg.openssl.winst
6060: 6f 72 65 3a 2f 2f 5d 22 2e 0a 0a 5b 69 74 65 6d ore://]"...[item
6070: 5d 0a 49 66 20 4f 70 65 6e 53 53 4c 20 69 73 20 ].If OpenSSL is
6080: 6e 6f 74 20 69 6e 73 74 61 6c 6c 65 64 20 6f 72 not installed or
6090: 20 74 68 65 20 43 41 20 63 65 72 74 69 66 69 63 the CA certific
60a0: 61 74 65 73 20 61 72 65 20 6e 6f 74 20 61 76 61 ates are not ava
60b0: 69 6c 61 62 6c 65 20 69 6e 20 50 45 4d 0a 66 6f ilable in PEM.fo
60c0: 72 6d 61 74 2c 20 74 68 65 20 43 41 20 63 65 72 rmat, the CA cer
60d0: 74 69 66 69 63 61 74 65 73 20 6d 75 73 74 20 62 tificates must b
60e0: 65 20 64 6f 77 6e 6c 6f 61 64 65 64 20 61 6e 64 e downloaded and
60f0: 20 69 6e 73 74 61 6c 6c 65 64 20 77 69 74 68 20 installed with
6100: 74 68 65 20 75 73 65 72 0a 73 6f 66 74 77 61 72 the user.softwar
6110: 65 2e 20 54 68 65 20 43 55 52 4c 20 74 65 61 6d e. The CURL team
6120: 20 6d 61 6b 65 73 20 74 68 65 6d 20 61 76 61 69 makes them avai
6130: 6c 61 62 6c 65 20 61 74 0a 5b 75 72 69 20 22 68 lable at.[uri "h
6140: 74 74 70 73 3a 2f 2f 63 75 72 6c 2e 73 65 2f 64 ttps://curl.se/d
6150: 6f 63 73 2f 63 61 65 78 74 72 61 63 74 2e 68 74 ocs/caextract.ht
6160: 6d 6c 22 20 22 43 41 20 63 65 72 74 69 66 69 63 ml" "CA certific
6170: 61 74 65 73 20 65 78 74 72 61 63 74 65 64 0a 66 ates extracted.f
6180: 72 6f 6d 20 4d 6f 7a 69 6c 6c 61 22 5d 20 69 6e rom Mozilla"] in
6190: 20 74 68 65 20 5b 66 69 6c 65 20 63 61 63 65 72 the [file cacer
61a0: 74 2e 70 65 6d 5d 20 66 69 6c 65 2e 20 59 6f 75 t.pem] file. You
61b0: 20 6d 75 73 74 20 74 68 65 6e 20 65 69 74 68 65 must then eithe
61c0: 72 20 73 65 74 20 74 68 65 0a 5b 76 61 72 20 53 r set the.[var S
61d0: 53 4c 5f 43 45 52 54 5f 44 49 52 5d 20 61 6e 64 SL_CERT_DIR] and
61e0: 2f 6f 72 20 5b 76 61 72 20 53 53 4c 5f 43 45 52 /or [var SSL_CER
61f0: 54 5f 46 49 4c 45 5d 20 65 6e 76 69 72 6f 6e 6d T_FILE] environm
6200: 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 6f 72 ent variables or
6210: 20 74 68 65 0a 5b 6f 70 74 69 6f 6e 20 2d 63 61 the.[option -ca
6220: 64 69 72 5d 20 6f 72 20 5b 6f 70 74 69 6f 6e 20 dir] or [option
6230: 2d 63 61 66 69 6c 65 5d 20 6f 70 74 69 6f 6e 73 -cafile] options
6240: 20 74 6f 20 74 68 65 20 43 41 20 63 65 72 74 20 to the CA cert
6250: 66 69 6c 65 27 73 20 69 6e 73 74 61 6c 6c 0a 6c file's install.l
6260: 6f 63 61 74 69 6f 6e 2e 20 49 74 20 69 73 20 79 ocation. It is y
6270: 6f 75 72 20 72 65 73 70 6f 6e 73 69 62 69 6c 69 our responsibili
6280: 74 79 20 74 6f 20 6b 65 65 70 20 74 68 69 73 20 ty to keep this
6290: 66 69 6c 65 20 75 70 20 74 6f 20 64 61 74 65 2e file up to date.
62a0: 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 73 ..[list_end]..[s
62b0: 65 63 74 69 6f 6e 20 22 43 61 6c 6c 62 61 63 6b ection "Callback
62c0: 20 4f 70 74 69 6f 6e 73 22 5d 0a 0a 41 73 20 70 Options"]..As p
62d0: 72 65 76 69 6f 75 73 6c 79 20 64 65 73 63 72 69 reviously descri
62e0: 62 65 64 2c 20 65 61 63 68 20 63 68 61 6e 6e 65 bed, each channe
62f0: 6c 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 l can be given t
6300: 68 65 69 72 20 6f 77 6e 20 63 61 6c 6c 62 61 63 heir own callbac
6310: 6b 73 0a 74 6f 20 68 61 6e 64 6c 65 20 69 6e 74 ks.to handle int
6320: 65 72 6d 65 64 69 61 74 65 20 70 72 6f 63 65 73 ermediate proces
6330: 73 69 6e 67 20 62 79 20 74 68 65 20 4f 70 65 6e sing by the Open
6340: 53 53 4c 20 6c 69 62 72 61 72 79 2c 20 75 73 69 SSL library, usi
6350: 6e 67 20 74 68 65 0a 5b 6f 70 74 69 6f 6e 20 2d ng the.[option -
6360: 63 6f 6d 6d 61 6e 64 5d 2c 20 5b 6f 70 74 69 6f command], [optio
6370: 6e 20 2d 70 61 73 73 77 6f 72 64 5d 2c 20 61 6e n -password], an
6380: 64 20 5b 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 64 d [option -valid
6390: 61 74 65 5f 63 6f 6d 6d 61 6e 64 5d 20 6f 70 74 ate_command] opt
63a0: 69 6f 6e 73 0a 70 61 73 73 65 64 20 74 6f 20 65 ions.passed to e
63b0: 69 74 68 65 72 20 6f 66 20 5b 63 6d 64 20 74 6c ither of [cmd tl
63c0: 73 3a 3a 73 6f 63 6b 65 74 5d 20 6f 72 20 5b 63 s::socket] or [c
63d0: 6d 64 20 74 6c 73 3a 3a 69 6d 70 6f 72 74 5d 2e md tls::import].
63e0: 0a 55 6e 6c 69 6b 65 20 70 72 65 76 69 6f 75 73 .Unlike previous
63f0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 54 63 6c versions of Tcl
6400: 54 4c 53 2c 20 6f 6e 6c 79 20 69 66 20 74 68 65 TLS, only if the
6410: 20 63 61 6c 6c 62 61 63 6b 20 67 65 6e 65 72 61 callback genera
6420: 74 65 73 20 61 6e 20 65 72 72 6f 72 2c 0a 77 69 tes an error,.wi
6430: 6c 6c 20 74 68 65 20 5b 73 79 73 63 6d 64 20 62 ll the [syscmd b
6440: 67 65 72 72 6f 72 5d 20 63 6f 6d 6d 61 6e 64 20 gerror] command
6450: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
6460: 74 68 65 20 65 72 72 6f 72 20 69 6e 66 6f 72 6d the error inform
6470: 61 74 69 6f 6e 2e 0a 0a 5b 73 75 62 73 65 63 74 ation...[subsect
6480: 69 6f 6e 20 22 56 61 6c 75 65 73 20 66 6f 72 20 ion "Values for
6490: 43 6f 6d 6d 61 6e 64 20 43 61 6c 6c 62 61 63 6b Command Callback
64a0: 22 5d 0a 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b "]..The callback
64b0: 20 66 6f 72 20 74 68 65 20 5b 6f 70 74 69 6f 6e for the [option
64c0: 20 2d 63 6f 6d 6d 61 6e 64 5d 20 6f 70 74 69 6f -command] optio
64d0: 6e 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 20 n is invoked at
64e0: 73 65 76 65 72 61 6c 20 70 6f 69 6e 74 73 20 64 several points d
64f0: 75 72 69 6e 67 20 74 68 65 0a 4f 70 65 6e 53 53 uring the.OpenSS
6500: 4c 20 68 61 6e 64 73 68 61 6b 65 20 61 6e 64 20 L handshake and
6510: 64 75 72 69 6e 67 20 72 6f 75 74 69 6e 65 20 6f during routine o
6520: 70 65 72 61 74 69 6f 6e 73 2e 20 53 65 65 20 62 perations. See b
6530: 65 6c 6f 77 20 66 6f 72 20 74 68 65 20 70 6f 73 elow for the pos
6540: 73 69 62 6c 65 0a 61 72 67 75 6d 65 6e 74 73 20 sible.arguments
6550: 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 63 61 passed to the ca
6560: 6c 6c 62 61 63 6b 20 73 63 72 69 70 74 2e 20 56 llback script. V
6570: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 66 alues returned f
6580: 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b rom the callback
6590: 20 61 72 65 0a 69 67 6e 6f 72 65 64 2e 0a 0a 5b are.ignored...[
65a0: 6c 69 73 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f list_begin optio
65b0: 6e 73 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 65 72 ns]..[opt_def er
65c0: 72 6f 72 20 5b 61 72 67 20 22 63 68 61 6e 6e 65 ror [arg "channe
65d0: 6c 49 64 20 6d 65 73 73 61 67 65 22 5d 5d 0a 54 lId message"]].T
65e0: 68 69 73 20 66 6f 72 6d 20 6f 66 20 63 61 6c 6c his form of call
65f0: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
6600: 77 68 65 6e 65 76 65 72 20 61 6e 20 65 72 72 6f whenever an erro
6610: 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
6620: 74 68 65 20 69 6e 69 74 69 61 6c 0a 63 6f 6e 6e the initial.conn
6630: 65 63 74 69 6f 6e 2c 20 68 61 6e 64 73 68 61 6b ection, handshak
6640: 65 2c 20 6f 72 20 49 2f 4f 20 6f 70 65 72 61 74 e, or I/O operat
6650: 69 6f 6e 73 2e 20 54 68 65 20 5b 61 72 67 20 6d ions. The [arg m
6660: 65 73 73 61 67 65 5d 20 61 72 67 75 6d 65 6e 74 essage] argument
6670: 20 63 61 6e 20 62 65 0a 66 72 6f 6d 20 74 68 65 can be.from the
6680: 20 54 63 6c 5f 45 72 72 6e 6f 4d 73 67 2c 20 4f Tcl_ErrnoMsg, O
6690: 70 65 6e 53 53 4c 20 66 75 6e 63 74 69 6f 6e 20 penSSL function
66a0: 5b 66 75 6e 20 45 52 52 5f 72 65 61 73 6f 6e 5f [fun ERR_reason_
66b0: 65 72 72 6f 72 5f 73 74 72 69 6e 67 28 29 5d 2c error_string()],
66c0: 0a 6f 72 20 61 20 63 75 73 74 6f 6d 20 6d 65 73 .or a custom mes
66d0: 73 61 67 65 2e 20 54 68 69 73 20 63 61 6c 6c 62 sage. This callb
66e0: 61 63 6b 20 69 73 20 6e 65 77 20 66 6f 72 20 54 ack is new for T
66f0: 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 6f 70 74 clTLS 1.8...[opt
6700: 5f 64 65 66 20 69 6e 66 6f 20 5b 61 72 67 20 22 _def info [arg "
6710: 63 68 61 6e 6e 65 6c 49 64 20 6d 61 6a 6f 72 20 channelId major
6720: 6d 69 6e 6f 72 20 6d 65 73 73 61 67 65 20 74 79 minor message ty
6730: 70 65 22 5d 5d 0a 54 68 69 73 20 66 6f 72 6d 20 pe"]].This form
6740: 6f 66 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 of callback is i
6750: 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 4f 70 nvoked by the Op
6760: 65 6e 53 53 4c 20 66 75 6e 63 74 69 6f 6e 0a 5b enSSL function.[
6770: 66 75 6e 20 53 53 4c 5f 73 65 74 5f 69 6e 66 6f fun SSL_set_info
6780: 5f 63 61 6c 6c 62 61 63 6b 28 29 5d 20 64 75 72 _callback()] dur
6790: 69 6e 67 20 74 68 65 20 69 6e 69 74 69 61 6c 20 ing the initial
67a0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 68 connection and h
67b0: 61 6e 64 73 68 61 6b 65 0a 6f 70 65 72 61 74 69 andshake.operati
67c0: 6f 6e 73 2e 20 54 68 65 20 61 72 67 75 6d 65 6e ons. The argumen
67d0: 74 73 20 61 72 65 3a 0a 0a 5b 6c 69 73 74 5f 62 ts are:..[list_b
67e0: 65 67 69 6e 20 64 65 66 69 6e 69 74 69 6f 6e 73 egin definitions
67f0: 5d 0a 0a 5b 64 65 66 20 5b 61 72 67 20 6d 61 6a ]..[def [arg maj
6800: 6f 72 5d 5d 0a 4d 61 6a 6f 72 20 63 61 74 65 67 or]].Major categ
6810: 6f 72 79 20 66 6f 72 20 65 72 72 6f 72 2e 20 56 ory for error. V
6820: 61 6c 69 64 20 65 6e 75 6d 73 20 61 72 65 3a 20 alid enums are:
6830: 5b 63 6f 6e 73 74 20 68 61 6e 64 73 68 61 6b 65 [const handshake
6840: 5d 2c 20 5b 63 6f 6e 73 74 20 61 6c 65 72 74 5d ], [const alert]
6850: 2c 0a 5b 63 6f 6e 73 74 20 63 6f 6e 6e 65 63 74 ,.[const connect
6860: 5d 2c 20 5b 63 6f 6e 73 74 20 61 63 63 65 70 74 ], [const accept
6870: 5d 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 6d 69 ]...[def [arg mi
6880: 6e 6f 72 5d 5d 0a 4d 69 6e 6f 72 20 63 61 74 65 nor]].Minor cate
6890: 67 6f 72 79 20 66 6f 72 20 65 72 72 6f 72 2e 20 gory for error.
68a0: 56 61 6c 69 64 20 65 6e 75 6d 73 20 61 72 65 3a Valid enums are:
68b0: 20 5b 63 6f 6e 73 74 20 73 74 61 72 74 5d 2c 20 [const start],
68c0: 5b 63 6f 6e 73 74 20 64 6f 6e 65 5d 2c 20 5b 63 [const done], [c
68d0: 6f 6e 73 74 20 72 65 61 64 5d 2c 0a 5b 63 6f 6e onst read],.[con
68e0: 73 74 20 77 72 69 74 65 5d 2c 20 5b 63 6f 6e 73 st write], [cons
68f0: 74 20 6c 6f 6f 70 5d 2c 20 5b 63 6f 6e 73 74 20 t loop], [const
6900: 65 78 69 74 5d 2e 0a 0a 5b 64 65 66 20 5b 61 72 exit]...[def [ar
6910: 67 20 6d 65 73 73 61 67 65 5d 5d 0a 44 65 73 63 g message]].Desc
6920: 72 69 70 74 69 76 65 20 6d 65 73 73 61 67 65 20 riptive message
6930: 73 74 72 69 6e 67 20 77 68 69 63 68 20 6d 61 79 string which may
6940: 20 62 65 20 67 65 6e 65 72 61 74 65 64 20 65 69 be generated ei
6950: 74 68 65 72 20 62 79 0a 5b 66 75 6e 20 53 53 4c ther by.[fun SSL
6960: 5f 73 74 61 74 65 5f 73 74 72 69 6e 67 5f 6c 6f _state_string_lo
6970: 6e 67 28 29 5d 20 6f 72 20 5b 66 75 6e 20 53 53 ng()] or [fun SS
6980: 4c 5f 61 6c 65 72 74 5f 64 65 73 63 5f 73 74 72 L_alert_desc_str
6990: 69 6e 67 5f 6c 6f 6e 67 28 29 5d 2c 0a 64 65 70 ing_long()],.dep
69a0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
69b0: 6e 74 65 78 74 2e 0a 0a 5b 64 65 66 20 5b 61 72 ntext...[def [ar
69c0: 67 20 74 79 70 65 5d 5d 0a 46 6f 72 20 61 6c 65 g type]].For ale
69d0: 72 74 73 2c 20 74 68 65 20 70 6f 73 73 69 62 6c rts, the possibl
69e0: 65 20 76 61 6c 75 65 73 20 61 72 65 3a 20 5b 63 e values are: [c
69f0: 6f 6e 73 74 20 77 61 72 6e 69 6e 67 5d 2c 0a 5b onst warning],.[
6a00: 63 6f 6e 73 74 20 66 61 74 61 6c 5d 2c 20 61 6e const fatal], an
6a10: 64 20 5b 63 6f 6e 73 74 20 75 6e 6b 6e 6f 77 6e d [const unknown
6a20: 5d 2e 20 46 6f 72 20 6f 74 68 65 72 73 2c 20 5b ]. For others, [
6a30: 63 6f 6e 73 74 20 69 6e 66 6f 5d 20 69 73 20 75 const info] is u
6a40: 73 65 64 2e 0a 54 68 69 73 20 61 72 67 75 6d 65 sed..This argume
6a50: 6e 74 20 69 73 20 6e 65 77 20 66 6f 72 20 54 63 nt is new for Tc
6a60: 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 6c 69 73 74 lTLS 1.8...[list
6a70: 5f 65 6e 64 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 _end]..[opt_def
6a80: 6d 65 73 73 61 67 65 20 5b 61 72 67 20 22 63 68 message [arg "ch
6a90: 61 6e 6e 65 6c 49 64 20 64 69 72 65 63 74 69 6f annelId directio
6aa0: 6e 20 76 65 72 73 69 6f 6e 20 63 6f 6e 74 65 6e n version conten
6ab0: 74 5f 74 79 70 65 20 6d 65 73 73 61 67 65 22 5d t_type message"]
6ac0: 5d 0a 54 68 69 73 20 66 6f 72 6d 20 6f 66 20 63 ].This form of c
6ad0: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
6ae0: 65 64 20 62 79 20 74 68 65 20 4f 70 65 6e 53 53 ed by the OpenSS
6af0: 4c 20 66 75 6e 63 74 69 6f 6e 0a 5b 66 75 6e 20 L function.[fun
6b00: 53 53 4c 5f 73 65 74 5f 6d 73 67 5f 63 61 6c 6c SSL_set_msg_call
6b10: 62 61 63 6b 28 29 5d 20 77 68 65 6e 65 76 65 72 back()] whenever
6b20: 20 61 20 6d 65 73 73 61 67 65 20 69 73 20 73 65 a message is se
6b30: 6e 74 20 6f 72 20 72 65 63 65 69 76 65 64 20 64 nt or received d
6b40: 75 72 69 6e 67 20 74 68 65 0a 69 6e 69 74 69 61 uring the.initia
6b50: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 68 61 l connection, ha
6b60: 6e 64 73 68 61 6b 65 2c 20 6f 72 20 49 2f 4f 20 ndshake, or I/O
6b70: 6f 70 65 72 61 74 69 6f 6e 73 2e 20 49 74 20 69 operations. It i
6b80: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
6b90: 20 77 68 65 6e 0a 4f 70 65 6e 53 53 4c 20 69 73 when.OpenSSL is
6ba0: 20 63 6f 6d 70 6c 69 65 64 20 77 69 74 68 20 74 complied with t
6bb0: 68 65 20 5b 63 6f 6e 73 74 20 65 6e 61 62 6c 65 he [const enable
6bc0: 2d 73 73 6c 2d 74 72 61 63 65 5d 20 6f 70 74 69 -ssl-trace] opti
6bd0: 6f 6e 2e 20 54 68 69 73 20 63 61 6c 6c 62 61 63 on. This callbac
6be0: 6b 20 69 73 0a 6e 65 77 20 66 6f 72 20 54 63 6c k is.new for Tcl
6bf0: 54 4c 53 20 31 2e 38 2e 20 54 68 65 20 61 72 67 TLS 1.8. The arg
6c00: 75 6d 65 6e 74 73 20 61 72 65 3a 0a 0a 5b 6c 69 uments are:..[li
6c10: 73 74 5f 62 65 67 69 6e 20 64 65 66 69 6e 69 74 st_begin definit
6c20: 69 6f 6e 73 5d 0a 0a 5b 64 65 66 20 5b 61 72 67 ions]..[def [arg
6c30: 20 64 69 72 65 63 74 69 6f 6e 5d 5d 0a 44 69 72 direction]].Dir
6c40: 65 63 74 69 6f 6e 20 69 73 20 65 69 74 68 65 72 ection is either
6c50: 20 5b 63 6f 6e 73 74 20 53 65 6e 74 5d 20 6f 72 [const Sent] or
6c60: 20 5b 63 6f 6e 73 74 20 52 65 63 65 69 76 65 64 [const Received
6c70: 5d 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 76 65 ]...[def [arg ve
6c80: 72 73 69 6f 6e 5d 5d 0a 56 65 72 73 69 6f 6e 20 rsion]].Version
6c90: 69 73 20 74 68 65 20 70 72 6f 74 6f 63 6f 6c 20 is the protocol
6ca0: 76 65 72 73 69 6f 6e 2e 0a 0a 5b 64 65 66 20 5b version...[def [
6cb0: 61 72 67 20 63 6f 6e 74 65 6e 74 5f 74 79 70 65 arg content_type
6cc0: 5d 5d 0a 43 6f 6e 74 65 6e 74 20 74 79 70 65 20 ]].Content type
6cd0: 69 73 20 74 68 65 20 6d 65 73 73 61 67 65 20 63 is the message c
6ce0: 6f 6e 74 65 6e 74 20 74 79 70 65 2e 0a 0a 5b 64 ontent type...[d
6cf0: 65 66 20 5b 61 72 67 20 6d 65 73 73 61 67 65 5d ef [arg message]
6d00: 5d 0a 4d 65 73 73 61 67 65 20 69 73 20 6d 6f 72 ].Message is mor
6d10: 65 20 69 6e 66 6f 20 66 72 6f 6d 20 74 68 65 20 e info from the
6d20: 5b 63 6f 6e 73 74 20 53 53 4c 5f 74 72 61 63 65 [const SSL_trace
6d30: 5d 20 41 50 49 2e 0a 0a 5b 6c 69 73 74 5f 65 6e ] API...[list_en
6d40: 64 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 73 65 73 d]..[opt_def ses
6d50: 73 69 6f 6e 20 5b 61 72 67 20 22 63 68 61 6e 6e sion [arg "chann
6d60: 65 6c 49 64 20 73 65 73 73 69 6f 6e 5f 69 64 20 elId session_id
6d70: 73 65 73 73 69 6f 6e 5f 74 69 63 6b 65 74 20 6c session_ticket l
6d80: 69 66 65 74 69 6d 65 22 5d 5d 0a 54 68 69 73 20 ifetime"]].This
6d90: 66 6f 72 6d 20 6f 66 20 63 61 6c 6c 62 61 63 6b form of callback
6da0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 is invoked by t
6db0: 68 65 20 4f 70 65 6e 53 53 4c 20 66 75 6e 63 74 he OpenSSL funct
6dc0: 69 6f 6e 0a 5b 66 75 6e 20 53 53 4c 5f 43 54 58 ion.[fun SSL_CTX
6dd0: 5f 73 65 73 73 5f 73 65 74 5f 6e 65 77 5f 63 62 _sess_set_new_cb
6de0: 28 29 5d 20 77 68 65 6e 65 76 65 72 20 61 20 6e ()] whenever a n
6df0: 65 77 20 73 65 73 73 69 6f 6e 20 69 64 20 69 73 ew session id is
6e00: 20 73 65 6e 74 20 62 79 20 74 68 65 0a 73 65 72 sent by the.ser
6e10: 76 65 72 20 64 75 72 69 6e 67 20 74 68 65 20 69 ver during the i
6e20: 6e 69 74 69 61 6c 20 63 6f 6e 6e 65 63 74 69 6f nitial connectio
6e30: 6e 20 61 6e 64 20 68 61 6e 64 73 68 61 6b 65 20 n and handshake
6e40: 61 6e 64 20 61 6c 73 6f 20 64 75 72 69 6e 67 20 and also during
6e50: 74 68 65 20 73 65 73 73 69 6f 6e 0a 69 66 20 74 the session.if t
6e60: 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 70 6f 73 74 he [option -post
6e70: 5f 68 61 6e 64 73 68 61 6b 65 5d 20 6f 70 74 69 _handshake] opti
6e80: 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 74 72 75 on is set to tru
6e90: 65 2e 20 54 68 69 73 20 63 61 6c 6c 62 61 63 6b e. This callback
6ea0: 20 69 73 20 6e 65 77 20 66 6f 72 0a 54 63 6c 54 is new for.TclT
6eb0: 4c 53 20 31 2e 38 2e 20 54 68 65 20 61 72 67 75 LS 1.8. The argu
6ec0: 6d 65 6e 74 73 20 61 72 65 3a 0a 0a 5b 6c 69 73 ments are:..[lis
6ed0: 74 5f 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 t_begin definiti
6ee0: 6f 6e 73 5d 0a 0a 5b 64 65 66 20 5b 61 72 67 20 ons]..[def [arg
6ef0: 73 65 73 73 69 6f 6e 5f 69 64 5d 5d 0a 53 65 73 session_id]].Ses
6f00: 73 69 6f 6e 20 49 64 20 69 73 20 74 68 65 20 63 sion Id is the c
6f10: 75 72 72 65 6e 74 20 73 65 73 73 69 6f 6e 20 69 urrent session i
6f20: 64 65 6e 74 69 66 69 65 72 0a 0a 5b 64 65 66 20 dentifier..[def
6f30: 5b 61 72 67 20 73 65 73 73 69 6f 6e 5f 74 69 63 [arg session_tic
6f40: 6b 65 74 5d 5d 0a 54 69 63 6b 65 74 20 69 73 20 ket]].Ticket is
6f50: 74 68 65 20 73 65 73 73 69 6f 6e 20 74 69 63 6b the session tick
6f60: 65 74 20 69 6e 66 6f 0a 0a 5b 64 65 66 20 5b 61 et info..[def [a
6f70: 72 67 20 6c 69 66 65 74 69 6d 65 5d 5d 0a 4c 69 rg lifetime]].Li
6f80: 66 65 74 69 6d 65 20 69 73 20 74 68 65 20 74 69 fetime is the ti
6f90: 63 6b 65 74 20 6c 69 66 65 74 69 6d 65 20 69 6e cket lifetime in
6fa0: 20 73 65 63 6f 6e 64 73 2e 0a 0a 5b 6c 69 73 74 seconds...[list
6fb0: 5f 65 6e 64 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 _end]..[opt_def
6fc0: 76 65 72 69 66 79 20 5b 61 72 67 20 22 63 68 61 verify [arg "cha
6fd0: 6e 6e 65 6c 49 64 20 64 65 70 74 68 20 63 65 72 nnelId depth cer
6fe0: 74 20 73 74 61 74 75 73 20 65 72 72 6f 72 22 5d t status error"]
6ff0: 5d 0a 54 68 69 73 20 63 61 6c 6c 62 61 63 6b 20 ].This callback
7000: 77 61 73 20 6d 6f 76 65 64 20 74 6f 20 5b 6f 70 was moved to [op
7010: 74 69 6f 6e 20 2d 76 61 6c 69 64 61 74 65 63 6f tion -validateco
7020: 6d 6d 61 6e 64 5d 20 69 6e 20 54 63 6c 54 4c 53 mmand] in TclTLS
7030: 20 31 2e 38 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 1.8...[list_end
7040: 5d 0a 0a 5b 73 75 62 73 65 63 74 69 6f 6e 20 22 ]..[subsection "
7050: 56 61 6c 75 65 73 20 66 6f 72 20 50 61 73 73 77 Values for Passw
7060: 6f 72 64 20 43 61 6c 6c 62 61 63 6b 22 5d 0a 0a ord Callback"]..
7070: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 The callback for
7080: 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 70 61 the [option -pa
7090: 73 73 77 6f 72 64 5d 20 6f 70 74 69 6f 6e 20 69 ssword] option i
70a0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 54 63 6c s invoked by Tcl
70b0: 54 4c 53 20 77 68 65 6e 65 76 65 72 20 4f 70 65 TLS whenever Ope
70c0: 6e 53 53 4c 20 6e 65 65 64 73 0a 74 6f 20 6f 62 nSSL needs.to ob
70d0: 74 61 69 6e 20 61 20 70 61 73 73 77 6f 72 64 2e tain a password.
70e0: 20 53 65 65 20 62 65 6c 6f 77 20 66 6f 72 20 74 See below for t
70f0: 68 65 20 70 6f 73 73 69 62 6c 65 20 61 72 67 75 he possible argu
7100: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74 6f 20 ments passed to
7110: 74 68 65 0a 63 61 6c 6c 62 61 63 6b 20 73 63 72 the.callback scr
7120: 69 70 74 2e 20 54 68 65 20 75 73 65 72 20 70 72 ipt. The user pr
7130: 6f 76 69 64 65 64 20 70 61 73 73 77 6f 72 64 20 ovided password
7140: 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 62 is expected to b
7150: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 e returned by th
7160: 65 0a 63 61 6c 6c 62 61 63 6b 2e 0a 0a 5b 6c 69 e.callback...[li
7170: 73 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f 6e 73 st_begin options
7180: 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 70 61 73 73 ]..[opt_def pass
7190: 77 6f 72 64 20 5b 61 72 67 20 22 72 77 66 6c 61 word [arg "rwfla
71a0: 67 20 73 69 7a 65 22 5d 5d 0a 49 6e 76 6f 6b 65 g size"]].Invoke
71b0: 64 20 77 68 65 6e 20 6c 6f 61 64 69 6e 67 20 6f d when loading o
71c0: 72 20 73 74 6f 72 69 6e 67 20 61 6e 20 65 6e 63 r storing an enc
71d0: 72 79 70 74 65 64 20 50 45 4d 20 63 65 72 74 69 rypted PEM certi
71e0: 66 69 63 61 74 65 2e 20 54 68 65 20 61 72 67 75 ficate. The argu
71f0: 6d 65 6e 74 73 20 61 72 65 3a 0a 0a 5b 6c 69 73 ments are:..[lis
7200: 74 5f 62 65 67 69 6e 20 64 65 66 69 6e 69 74 69 t_begin definiti
7210: 6f 6e 73 5d 0a 0a 5b 64 65 66 20 5b 61 72 67 20 ons]..[def [arg
7220: 72 77 66 6c 61 67 5d 5d 0a 54 68 65 20 72 65 61 rwflag]].The rea
7230: 64 2f 77 72 69 74 65 20 66 6c 61 67 20 69 73 20 d/write flag is
7240: 30 20 66 6f 72 20 72 65 61 64 69 6e 67 2f 64 65 0 for reading/de
7250: 63 72 79 70 74 69 6f 6e 20 6f 72 20 31 20 66 6f cryption or 1 fo
7260: 72 20 77 72 69 74 69 6e 67 2f 65 6e 63 72 79 70 r writing/encryp
7270: 74 69 6f 6e 2e 0a 54 68 65 20 6c 61 74 74 65 72 tion..The latter
7280: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
7290: 64 65 74 65 72 6d 69 6e 65 20 77 68 65 6e 20 74 determine when t
72a0: 6f 20 70 72 6f 6d 70 74 20 74 68 65 20 75 73 65 o prompt the use
72b0: 72 20 74 6f 20 63 6f 6e 66 69 72 6d 2e 0a 54 68 r to confirm..Th
72c0: 69 73 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e is argument is n
72d0: 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e ew for TclTLS 1.
72e0: 38 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 73 69 8...[def [arg si
72f0: 7a 65 5d 5d 0a 54 68 65 20 73 69 7a 65 20 69 73 ze]].The size is
7300: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
7310: 67 74 68 20 6f 66 20 74 68 65 20 70 61 73 73 77 gth of the passw
7320: 6f 72 64 20 69 6e 20 62 79 74 65 73 2e 0a 54 68 ord in bytes..Th
7330: 69 73 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e is argument is n
7340: 65 77 20 66 6f 72 20 54 63 6c 54 4c 53 20 31 2e ew for TclTLS 1.
7350: 38 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 8...[list_end]..
7360: 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 5b 73 75 62 [list_end]..[sub
7370: 73 65 63 74 69 6f 6e 20 22 56 61 6c 75 65 73 20 section "Values
7380: 66 6f 72 20 56 61 6c 69 64 61 74 65 20 43 6f 6d for Validate Com
7390: 6d 61 6e 64 20 43 61 6c 6c 62 61 63 6b 22 5d 0a mand Callback"].
73a0: 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 6f .The callback fo
73b0: 72 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 76 r the [option -v
73c0: 61 6c 69 64 61 74 65 63 6f 6d 6d 61 6e 64 5d 20 alidatecommand]
73d0: 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 option is invoke
73e0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 68 61 6e d during the han
73f0: 64 73 68 61 6b 65 0a 70 72 6f 63 65 73 73 20 69 dshake.process i
7400: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 n order for the
7410: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 application to v
7420: 61 6c 69 64 61 74 65 20 74 68 65 20 70 72 6f 76 alidate the prov
7430: 69 64 65 64 20 76 61 6c 75 65 28 73 29 2e 20 53 ided value(s). S
7440: 65 65 0a 62 65 6c 6f 77 20 66 6f 72 20 74 68 65 ee.below for the
7450: 20 70 6f 73 73 69 62 6c 65 20 61 72 67 75 6d 65 possible argume
7460: 6e 74 73 20 70 61 73 73 65 64 20 74 6f 20 74 68 nts passed to th
7470: 65 20 63 61 6c 6c 62 61 63 6b 20 73 63 72 69 70 e callback scrip
7480: 74 2e 20 49 66 20 6e 6f 74 0a 73 70 65 63 69 66 t. If not.specif
7490: 69 65 64 2c 20 4f 70 65 6e 53 53 4c 20 77 69 6c ied, OpenSSL wil
74a0: 6c 20 61 63 63 65 70 74 20 61 6c 6c 20 76 61 6c l accept all val
74b0: 69 64 20 63 65 72 74 69 66 69 63 61 74 65 73 20 id certificates
74c0: 61 6e 64 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 and extensions.
74d0: 54 6f 20 72 65 6a 65 63 74 0a 74 68 65 20 76 61 To reject.the va
74e0: 6c 75 65 20 61 6e 64 20 61 62 6f 72 74 20 74 68 lue and abort th
74f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 e connection, th
7500: 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c e callback shoul
7510: 64 20 72 65 74 75 72 6e 20 30 2e 20 54 6f 20 61 d return 0. To a
7520: 63 63 65 70 74 20 74 68 65 0a 76 61 6c 75 65 20 ccept the.value
7530: 61 6e 64 20 63 6f 6e 74 69 6e 75 65 20 74 68 65 and continue the
7540: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 69 74 20 connection, it
7550: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e should return 1.
7560: 20 54 6f 20 72 65 6a 65 63 74 20 74 68 65 20 76 To reject the v
7570: 61 6c 75 65 2c 20 62 75 74 0a 63 6f 6e 74 69 6e alue, but.contin
7580: 75 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ue the connectio
7590: 6e 2c 20 69 74 20 73 68 6f 75 6c 64 20 72 65 74 n, it should ret
75a0: 75 72 6e 20 32 2e 20 54 68 69 73 20 63 61 6c 6c urn 2. This call
75b0: 62 61 63 6b 20 69 73 20 6e 65 77 20 66 6f 72 20 back is new for
75c0: 54 63 6c 54 4c 53 20 31 2e 38 2e 0a 0a 5b 6c 69 TclTLS 1.8...[li
75d0: 73 74 5f 62 65 67 69 6e 20 6f 70 74 69 6f 6e 73 st_begin options
75e0: 5d 0a 0a 5b 6f 70 74 5f 64 65 66 20 61 6c 70 6e ]..[opt_def alpn
75f0: 20 5b 61 72 67 20 22 63 68 61 6e 6e 65 6c 49 64 [arg "channelId
7600: 20 70 72 6f 74 6f 63 6f 6c 20 6d 61 74 63 68 22 protocol match"
7610: 5d 5d 0a 46 6f 72 20 73 65 72 76 65 72 73 2c 20 ]].For servers,
7620: 74 68 69 73 20 66 6f 72 6d 20 6f 66 20 63 61 6c this form of cal
7630: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
7640: 20 77 68 65 6e 20 74 68 65 20 63 6c 69 65 6e 74 when the client
7650: 20 41 4c 50 4e 20 65 78 74 65 6e 73 69 6f 6e 20 ALPN extension
7660: 69 73 0a 72 65 63 65 69 76 65 64 2e 20 49 66 20 is.received. If
7670: 5b 61 72 67 20 6d 61 74 63 68 5d 20 69 73 20 74 [arg match] is t
7680: 72 75 65 2c 20 74 68 65 6e 20 5b 61 72 67 20 70 rue, then [arg p
7690: 72 6f 74 6f 63 6f 6c 5d 20 69 73 20 74 68 65 20 rotocol] is the
76a0: 66 69 72 73 74 0a 5b 6f 70 74 69 6f 6e 20 2d 61 first.[option -a
76b0: 6c 70 6e 5d 20 70 72 6f 74 6f 63 6f 6c 20 6f 70 lpn] protocol op
76c0: 74 69 6f 6e 20 69 6e 20 63 6f 6d 6d 6f 6e 20 74 tion in common t
76d0: 6f 20 62 6f 74 68 20 74 68 65 20 63 6c 69 65 6e o both the clien
76e0: 74 20 61 6e 64 20 73 65 72 76 65 72 2e 0a 49 66 t and server..If
76f0: 20 6e 6f 74 2c 20 74 68 65 20 66 69 72 73 74 20 not, the first
7700: 63 6c 69 65 6e 74 20 73 70 65 63 69 66 69 65 64 client specified
7710: 20 70 72 6f 74 6f 63 6f 6c 20 69 73 20 75 73 65 protocol is use
7720: 64 2e 20 54 68 69 73 20 63 61 6c 6c 62 61 63 6b d. This callback
7730: 20 69 73 20 63 61 6c 6c 65 64 0a 61 66 74 65 72 is called.after
7740: 20 74 68 65 20 48 65 6c 6c 6f 20 61 6e 64 20 41 the Hello and A
7750: 4c 50 4e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 0a LPN callbacks...
7760: 5b 6f 70 74 5f 64 65 66 20 68 65 6c 6c 6f 20 5b [opt_def hello [
7770: 61 72 67 20 22 63 68 61 6e 6e 65 6c 49 64 20 73 arg "channelId s
7780: 65 72 76 65 72 6e 61 6d 65 22 5d 5d 0a 46 6f 72 ervername"]].For
7790: 20 73 65 72 76 65 72 73 2c 20 74 68 69 73 20 66 servers, this f
77a0: 6f 72 6d 20 6f 66 20 63 61 6c 6c 62 61 63 6b 20 orm of callback
77b0: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
77c0: 67 20 63 6c 69 65 6e 74 20 68 65 6c 6c 6f 20 6d g client hello m
77d0: 65 73 73 61 67 65 0a 70 72 6f 63 65 73 73 69 6e essage.processin
77e0: 67 2e 20 54 68 65 20 70 75 72 70 6f 73 65 20 69 g. The purpose i
77f0: 73 20 73 6f 20 74 68 65 20 73 65 72 76 65 72 20 s so the server
7800: 63 61 6e 20 73 65 6c 65 63 74 20 74 68 65 20 61 can select the a
7810: 70 70 72 6f 70 72 69 61 74 65 20 63 65 72 74 69 ppropriate certi
7820: 66 69 63 61 74 65 0a 74 6f 20 70 72 65 73 65 6e ficate.to presen
7830: 74 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 2c t to the client,
7840: 20 61 6e 64 20 74 6f 20 6d 61 6b 65 20 6f 74 68 and to make oth
7850: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
7860: 20 61 64 6a 75 73 74 6d 65 6e 74 73 20 72 65 6c adjustments rel
7870: 65 76 61 6e 74 0a 74 6f 20 74 68 61 74 20 73 65 evant.to that se
7880: 72 76 65 72 20 6e 61 6d 65 20 61 6e 64 20 69 74 rver name and it
7890: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e s configuration.
78a0: 20 49 74 20 69 73 20 63 61 6c 6c 65 64 20 62 65 It is called be
78b0: 66 6f 72 65 20 74 68 65 20 53 4e 49 20 61 6e 64 fore the SNI and
78c0: 20 41 4c 50 4e 0a 63 61 6c 6c 62 61 63 6b 73 2e ALPN.callbacks.
78d0: 0a 0a 5b 6f 70 74 5f 64 65 66 20 73 6e 69 20 5b ..[opt_def sni [
78e0: 61 72 67 20 22 63 68 61 6e 6e 65 6c 49 64 20 73 arg "channelId s
78f0: 65 72 76 65 72 6e 61 6d 65 22 5d 5d 0a 46 6f 72 ervername"]].For
7900: 20 73 65 72 76 65 72 73 2c 20 74 68 69 73 20 66 servers, this f
7910: 6f 72 6d 20 6f 66 20 63 61 6c 6c 62 61 63 6b 20 orm of callback
7920: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
7930: 74 68 65 20 53 65 72 76 65 72 20 4e 61 6d 65 20 the Server Name
7940: 49 6e 64 69 63 61 74 69 6f 6e 0a 28 53 4e 49 29 Indication.(SNI)
7950: 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 72 65 extension is re
7960: 63 65 69 76 65 64 2e 20 54 68 65 20 5b 61 72 67 ceived. The [arg
7970: 20 73 65 72 76 65 72 6e 61 6d 65 5d 20 61 72 67 servername] arg
7980: 75 6d 65 6e 74 20 69 73 20 74 68 65 20 63 6c 69 ument is the cli
7990: 65 6e 74 0a 70 72 6f 76 69 64 65 64 20 73 65 72 ent.provided ser
79a0: 76 65 72 20 6e 61 6d 65 20 73 70 65 63 69 66 69 ver name specifi
79b0: 65 64 20 69 6e 20 74 68 65 20 5b 6f 70 74 69 6f ed in the [optio
79c0: 6e 20 2d 73 65 72 76 65 72 6e 61 6d 65 3c 2f 62 n -servername</b
79d0: 3e 5d 20 6f 70 74 69 6f 6e 2e 20 54 68 65 0a 70 >] option. The.p
79e0: 75 72 70 6f 73 65 20 69 73 20 73 6f 20 77 68 65 urpose is so whe
79f0: 6e 20 61 20 73 65 72 76 65 72 20 73 75 70 70 6f n a server suppo
7a00: 72 74 73 20 6d 75 6c 74 69 70 6c 65 20 6e 61 6d rts multiple nam
7a10: 65 73 2c 20 74 68 65 20 72 69 67 68 74 20 63 65 es, the right ce
7a20: 72 74 69 66 69 63 61 74 65 0a 63 61 6e 20 62 65 rtificate.can be
7a30: 20 75 73 65 64 2e 20 49 74 20 69 73 20 63 61 6c used. It is cal
7a40: 6c 65 64 20 61 66 74 65 72 20 74 68 65 20 68 65 led after the he
7a50: 6c 6c 6f 20 63 61 6c 6c 62 61 63 6b 20 62 75 74 llo callback but
7a60: 20 62 65 66 6f 72 65 20 74 68 65 20 41 4c 50 4e before the ALPN
7a70: 0a 63 61 6c 6c 62 61 63 6b 2e 0a 0a 5b 6f 70 74 .callback...[opt
7a80: 5f 64 65 66 20 76 65 72 69 66 79 20 5b 61 72 67 _def verify [arg
7a90: 20 22 63 68 61 6e 6e 65 6c 49 64 20 64 65 70 74 "channelId dept
7aa0: 68 20 63 65 72 74 20 73 74 61 74 75 73 20 65 72 h cert status er
7ab0: 72 6f 72 22 5d 5d 0a 54 68 69 73 20 66 6f 72 6d ror"]].This form
7ac0: 20 6f 66 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 of callback is
7ad0: 69 6e 76 6f 6b 65 64 20 62 79 20 4f 70 65 6e 53 invoked by OpenS
7ae0: 53 4c 20 77 68 65 6e 20 61 20 6e 65 77 20 63 65 SL when a new ce
7af0: 72 74 69 66 69 63 61 74 65 20 69 73 20 72 65 63 rtificate is rec
7b00: 65 69 76 65 64 0a 66 72 6f 6d 20 74 68 65 20 70 eived.from the p
7b10: 65 65 72 2e 20 49 74 20 61 6c 6c 6f 77 73 20 74 eer. It allows t
7b20: 68 65 20 63 6c 69 65 6e 74 20 74 6f 20 63 68 65 he client to che
7b30: 63 6b 20 74 68 65 20 63 65 72 74 69 66 69 63 61 ck the certifica
7b40: 74 65 20 76 65 72 69 66 69 63 61 74 69 6f 6e 0a te verification.
7b50: 72 65 73 75 6c 74 73 20 61 6e 64 20 63 68 6f 6f results and choo
7b60: 73 65 20 77 68 65 74 68 65 72 20 74 6f 20 63 6f se whether to co
7b70: 6e 74 69 6e 75 65 20 6f 72 20 6e 6f 74 2e 20 49 ntinue or not. I
7b80: 74 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 t is called for
7b90: 65 61 63 68 0a 63 65 72 74 69 66 69 63 61 74 65 each.certificate
7ba0: 20 69 6e 20 74 68 65 20 63 65 72 74 69 66 69 63 in the certific
7bb0: 61 74 65 20 63 68 61 69 6e 2e 20 54 68 69 73 20 ate chain. This
7bc0: 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 6d 6f 76 callback was mov
7bd0: 65 64 20 66 72 6f 6d 0a 5b 6f 70 74 69 6f 6e 20 ed from.[option
7be0: 2d 63 6f 6d 6d 61 6e 64 5d 20 69 6e 20 54 63 6c -command] in Tcl
7bf0: 54 4c 53 20 31 2e 38 2e 20 54 68 65 20 61 72 67 TLS 1.8. The arg
7c00: 75 6d 65 6e 74 73 20 61 72 65 3a 0a 0a 5b 6c 69 uments are:..[li
7c10: 73 74 5f 62 65 67 69 6e 20 64 65 66 69 6e 69 74 st_begin definit
7c20: 69 6f 6e 73 5d 0a 0a 5b 64 65 66 20 5b 61 72 67 ions]..[def [arg
7c30: 20 64 65 70 74 68 5d 5d 0a 54 68 65 20 64 65 70 depth]].The dep
7c40: 74 68 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 th is the intege
7c50: 72 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 63 r depth of the c
7c60: 65 72 74 69 66 69 63 61 74 65 20 69 6e 20 74 68 ertificate in th
7c70: 65 20 63 65 72 74 69 66 69 63 61 74 65 20 63 68 e certificate ch
7c80: 61 69 6e 2c 0a 77 68 65 72 65 20 30 20 69 73 20 ain,.where 0 is
7c90: 74 68 65 20 70 65 65 72 20 63 65 72 74 69 66 69 the peer certifi
7ca0: 63 61 74 65 20 61 6e 64 20 68 69 67 68 65 72 20 cate and higher
7cb0: 76 61 6c 75 65 73 20 67 6f 69 6e 67 20 75 70 20 values going up
7cc0: 74 6f 20 74 68 65 20 43 65 72 74 69 66 69 63 61 to the Certifica
7cd0: 74 65 0a 41 75 74 68 6f 72 69 74 79 20 28 43 41 te.Authority (CA
7ce0: 29 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 63 65 )...[def [arg ce
7cf0: 72 74 5d 5d 0a 54 68 65 20 63 65 72 74 20 61 72 rt]].The cert ar
7d00: 67 75 6d 65 6e 74 20 69 73 20 61 20 6c 69 73 74 gument is a list
7d10: 20 6f 66 20 6b 65 79 2d 76 61 6c 75 65 20 70 61 of key-value pa
7d20: 69 72 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 irs similar to t
7d30: 68 6f 73 65 20 72 65 74 75 72 6e 65 64 20 62 79 hose returned by
7d40: 0a 5b 63 6d 64 20 74 6c 73 3a 3a 73 74 61 74 75 .[cmd tls::statu
7d50: 73 5d 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 73 s]...[def [arg s
7d60: 74 61 74 75 73 5d 5d 0a 54 68 65 20 73 74 61 74 tatus]].The stat
7d70: 75 73 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 us argument is t
7d80: 68 65 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 69 64 he boolean valid
7d90: 69 74 79 20 6f 66 20 74 68 65 20 63 75 72 72 65 ity of the curre
7da0: 6e 74 20 63 65 72 74 69 66 69 63 61 74 65 20 77 nt certificate w
7db0: 68 65 72 65 20 30 0a 69 73 20 69 6e 76 61 6c 69 here 0.is invali
7dc0: 64 20 61 6e 64 20 31 20 69 73 20 76 61 6c 69 64 d and 1 is valid
7dd0: 2e 0a 0a 5b 64 65 66 20 5b 61 72 67 20 65 72 72 ...[def [arg err
7de0: 6f 72 5d 5d 0a 54 68 65 20 65 72 72 6f 72 20 61 or]].The error a
7df0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 65 rgument is the e
7e00: 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 69 66 rror message, if
7e10: 20 61 6e 79 2c 20 67 65 6e 65 72 61 74 65 64 20 any, generated
7e20: 62 79 0a 5b 66 75 6e 20 58 35 30 39 5f 53 54 4f by.[fun X509_STO
7e30: 52 45 5f 43 54 58 5f 67 65 74 5f 65 72 72 6f 72 RE_CTX_get_error
7e40: 28 29 5d 2e 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d ()]...[list_end]
7e50: 0a 0a 5b 6c 69 73 74 5f 65 6e 64 5d 0a 0a 52 65 ..[list_end]..Re
7e60: 66 65 72 65 6e 63 65 20 69 6d 70 6c 65 6d 65 6e ference implemen
7e70: 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 tations of these
7e80: 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 70 callbacks are p
7e90: 72 6f 76 69 64 65 64 20 69 6e 20 5b 66 69 6c 65 rovided in [file
7ea0: 20 74 6c 73 2e 74 63 6c 5d 0a 61 73 20 5b 63 6d tls.tcl].as [cm
7eb0: 64 20 74 6c 73 3a 3a 63 61 6c 6c 62 61 63 6b 5d d tls::callback]
7ec0: 2c 20 5b 63 6d 64 20 74 6c 73 3a 3a 70 61 73 73 , [cmd tls::pass
7ed0: 77 6f 72 64 5d 2c 20 61 6e 64 20 5b 63 6d 64 20 word], and [cmd
7ee0: 74 6c 73 3a 3a 76 61 6c 69 64 61 74 65 5f 63 6f tls::validate_co
7ef0: 6d 6d 61 6e 64 5d 0a 72 65 73 70 65 63 74 69 76 mmand].respectiv
7f00: 65 6c 79 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ely. Note that t
7f10: 68 65 73 65 20 61 72 65 20 6f 6e 6c 79 20 5b 65 hese are only [e
7f20: 6d 70 68 20 73 61 6d 70 6c 65 5d 20 69 6d 70 6c mph sample] impl
7f30: 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 20 49 6e 20 ementations. In
7f40: 61 20 6d 6f 72 65 0a 72 65 61 6c 69 73 74 69 63 a more.realistic
7f50: 20 64 65 70 6c 6f 79 6d 65 6e 74 20 79 6f 75 20 deployment you
7f60: 77 6f 75 6c 64 20 73 70 65 63 69 66 79 20 79 6f would specify yo
7f70: 75 72 20 6f 77 6e 20 63 61 6c 6c 62 61 63 6b 20 ur own callback
7f80: 73 63 72 69 70 74 73 20 6f 6e 20 65 61 63 68 20 scripts on each
7f90: 54 4c 53 0a 63 68 61 6e 6e 65 6c 20 75 73 69 6e TLS.channel usin
7fa0: 67 20 74 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 63 g the [option -c
7fb0: 6f 6d 6d 61 6e 64 5d 2c 20 5b 6f 70 74 69 6f 6e ommand], [option
7fc0: 20 2d 70 61 73 73 77 6f 72 64 5d 2c 20 61 6e 64 -password], and
7fd0: 0a 5b 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 64 61 .[option -valida
7fe0: 74 65 5f 63 6f 6d 6d 61 6e 64 5d 20 6f 70 74 69 te_command] opti
7ff0: 6f 6e 73 2e 0a 0a 5b 70 61 72 61 5d 0a 0a 54 68 ons...[para]..Th
8000: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
8010: 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 6f 70 74 or when the [opt
8020: 69 6f 6e 20 2d 63 6f 6d 6d 61 6e 64 5d 20 61 6e ion -command] an
8030: 64 20 5b 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 64 d [option -valid
8040: 61 74 65 5f 63 6f 6d 6d 61 6e 64 5d 0a 6f 70 74 ate_command].opt
8050: 69 6f 6e 73 20 61 72 65 20 6e 6f 74 20 73 70 65 ions are not spe
8060: 63 69 66 69 65 64 2c 20 69 73 20 66 6f 72 20 54 cified, is for T
8070: 63 6c 54 4c 53 20 74 6f 20 70 72 6f 63 65 73 73 clTLS to process
8080: 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 the associated
8090: 6c 69 62 72 61 72 79 0a 63 61 6c 6c 62 61 63 6b library.callback
80a0: 73 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 54 68 s internally. Th
80b0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
80c0: 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 6f 70 74 or when the [opt
80d0: 69 6f 6e 20 2d 70 61 73 73 77 6f 72 64 5d 20 6f ion -password] o
80e0: 70 74 69 6f 6e 0a 69 73 20 6e 6f 74 20 73 70 65 ption.is not spe
80f0: 63 69 66 69 65 64 20 69 73 20 66 6f 72 20 54 63 cified is for Tc
8100: 6c 54 4c 53 20 74 6f 20 70 72 6f 63 65 73 73 20 lTLS to process
8110: 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6c the associated l
8120: 69 62 72 61 72 79 20 63 61 6c 6c 62 61 63 6b 73 ibrary callbacks
8130: 20 62 79 0a 61 74 74 65 6d 70 74 69 6e 67 20 74 by.attempting t
8140: 6f 20 63 61 6c 6c 20 5b 63 6d 64 20 74 6c 73 3a o call [cmd tls:
8150: 3a 70 61 73 73 77 6f 72 64 5d 2e 20 54 68 65 20 :password]. The
8160: 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 difference betwe
8170: 65 6e 20 74 68 65 73 65 20 74 77 6f 0a 62 65 68 en these two.beh
8180: 61 76 69 6f 72 73 20 69 73 20 61 20 63 6f 6e 73 aviors is a cons
8190: 65 71 75 65 6e 63 65 20 6f 66 20 6d 61 69 6e 74 equence of maint
81a0: 61 69 6e 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 aining compatibi
81b0: 6c 69 74 79 20 77 69 74 68 20 65 61 72 6c 69 65 lity with earlie
81c0: 72 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e r.implementation
81d0: 73 2e 0a 0a 5b 70 61 72 61 5d 0a 0a 5b 65 6d 70 s...[para]..[emp
81e0: 68 20 22 54 68 65 20 75 73 65 20 6f 66 20 74 68 h "The use of th
81f0: 65 20 72 65 66 65 72 65 6e 63 65 20 63 61 6c 6c e reference call
8200: 62 61 63 6b 73 20 5b 63 6d 64 20 74 6c 73 3a 3a backs [cmd tls::
8210: 63 61 6c 6c 62 61 63 6b 5d 2c 20 5b 63 6d 64 20 callback], [cmd
8220: 74 6c 73 3a 3a 70 61 73 73 77 6f 72 64 5d 2c 0a tls::password],.
8230: 61 6e 64 20 5b 63 6d 64 20 74 6c 73 3a 3a 76 61 and [cmd tls::va
8240: 6c 69 64 61 74 65 5f 63 6f 6d 6d 61 6e 64 5d 20 lidate_command]
8250: 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 is not recommend
8260: 65 64 2e 20 54 68 65 79 20 6d 61 79 20 62 65 20 ed. They may be
8270: 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 66 75 74 removed from fut
8280: 75 72 65 20 72 65 6c 65 61 73 65 73 2e 22 5d 0a ure releases."].
8290: 0a 5b 73 65 63 74 69 6f 6e 20 44 65 62 75 67 5d .[section Debug]
82a0: 0a 0a 46 6f 72 20 6d 6f 73 74 20 64 65 62 75 67 ..For most debug
82b0: 67 69 6e 67 20 6e 65 65 64 73 2c 20 74 68 65 20 ging needs, the
82c0: 5b 6f 70 74 69 6f 6e 20 2d 63 61 6c 6c 62 61 63 [option -callbac
82d0: 6b 5d 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 k] option can be
82e0: 20 75 73 65 64 20 74 6f 20 70 72 6f 76 69 64 65 used to provide
82f0: 0a 73 75 66 66 69 63 69 65 6e 74 20 69 6e 73 69 .sufficient insi
8300: 67 68 74 20 61 6e 64 20 69 6e 66 6f 72 6d 61 74 ght and informat
8310: 69 6f 6e 20 6f 6e 20 74 68 65 20 54 4c 53 20 68 ion on the TLS h
8320: 61 6e 64 73 68 61 6b 65 20 61 6e 64 20 70 72 6f andshake and pro
8330: 67 72 65 73 73 2e 20 49 66 0a 66 75 72 74 68 65 gress. If.furthe
8340: 72 20 74 72 6f 75 62 6c 65 73 68 6f 6f 74 69 6e r troubleshootin
8350: 67 20 69 6e 73 69 67 68 74 20 69 73 20 6e 65 65 g insight is nee
8360: 64 65 64 2c 20 74 68 65 20 63 6f 6d 70 69 6c 65 ded, the compile
8370: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 5b 6f 70 time option.[op
8380: 74 69 6f 6e 20 2d 2d 65 6e 61 62 6c 65 2d 64 65 tion --enable-de
8390: 62 75 67 5d 20 63 61 6e 20 62 65 20 75 73 65 64 bug] can be used
83a0: 20 74 6f 20 67 65 74 20 64 65 74 61 69 6c 65 64 to get detailed
83b0: 20 65 78 65 63 75 74 69 6f 6e 20 66 6c 6f 77 20 execution flow
83c0: 73 74 61 74 75 73 2e 0a 0a 5b 70 61 72 61 5d 0a status...[para].
83d0: 0a 54 4c 53 20 6b 65 79 20 6c 6f 67 67 69 6e 67 .TLS key logging
83e0: 20 63 61 6e 20 62 65 20 65 6e 61 62 6c 65 64 20 can be enabled
83f0: 62 79 20 73 65 74 74 69 6e 67 20 74 68 65 20 65 by setting the e
8400: 6e 76 69 72 6f 6e 6d 65 6e 74 20 76 61 72 69 61 nvironment varia
8410: 62 6c 65 0a 5b 76 61 72 20 53 53 4c 4b 45 59 4c ble.[var SSLKEYL
8420: 4f 47 46 49 4c 45 5d 20 74 6f 20 74 68 65 20 6e OGFILE] to the n
8430: 61 6d 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ame of the file
8440: 74 6f 20 6c 6f 67 20 74 6f 2e 20 54 68 65 6e 20 to log to. Then
8450: 77 68 65 6e 65 76 65 72 20 54 4c 53 20 6b 65 79 whenever TLS key
8460: 0a 6d 61 74 65 72 69 61 6c 20 69 73 20 67 65 6e .material is gen
8470: 65 72 61 74 65 64 20 6f 72 20 72 65 63 65 69 76 erated or receiv
8480: 65 64 20 69 74 20 77 69 6c 6c 20 62 65 20 6c 6f ed it will be lo
8490: 67 67 65 64 20 74 6f 20 74 68 65 20 66 69 6c 65 gged to the file
84a0: 2e 20 54 68 69 73 20 69 73 20 75 73 65 66 75 6c . This is useful
84b0: 0a 66 6f 72 20 6c 6f 67 67 69 6e 67 20 6b 65 79 .for logging key
84c0: 20 64 61 74 61 20 66 6f 72 20 6e 65 74 77 6f 72 data for networ
84d0: 6b 20 6c 6f 67 67 69 6e 67 20 74 6f 6f 6c 73 20 k logging tools
84e0: 74 6f 20 75 73 65 20 74 6f 20 64 65 63 72 79 70 to use to decryp
84f0: 74 20 74 68 65 20 64 61 74 61 2e 0a 0a 5b 70 61 t the data...[pa
8500: 72 61 5d 0a 0a 54 68 65 20 5b 76 61 72 20 74 6c ra]..The [var tl
8510: 73 3a 3a 64 65 62 75 67 5d 20 76 61 72 69 61 62 s::debug] variab
8520: 6c 65 20 70 72 6f 76 69 64 65 73 20 73 6f 6d 65 le provides some
8530: 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 additional cont
8540: 72 6f 6c 20 6f 76 65 72 20 74 68 65 0a 64 65 62 rol over the.deb
8550: 75 67 20 6c 6f 67 67 69 6e 67 20 69 6e 20 74 68 ug logging in th
8560: 65 20 5b 63 6d 64 20 74 6c 73 3a 3a 63 61 6c 6c e [cmd tls::call
8570: 62 61 63 6b 5d 2c 20 5b 63 6d 64 20 74 6c 73 3a back], [cmd tls:
8580: 3a 70 61 73 73 77 6f 72 64 5d 2c 20 61 6e 64 0a :password], and.
8590: 5b 63 6d 64 20 74 6c 73 3a 3a 76 61 6c 69 64 61 [cmd tls::valida
85a0: 74 65 5f 63 6f 6d 6d 61 6e 64 5d 20 64 65 66 61 te_command] defa
85b0: 75 6c 74 20 68 61 6e 64 6c 65 72 73 20 69 6e 20 ult handlers in
85c0: 5b 66 69 6c 65 20 74 6c 73 2e 74 63 6c 5d 2e 0a [file tls.tcl]..
85d0: 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
85e0: 65 20 69 73 20 30 20 77 69 74 68 20 68 69 67 68 e is 0 with high
85f0: 65 72 20 76 61 6c 75 65 73 20 70 72 6f 64 75 63 er values produc
8600: 69 6e 67 20 6d 6f 72 65 20 64 69 61 67 6e 6f 73 ing more diagnos
8610: 74 69 63 20 6f 75 74 70 75 74 2c 0a 61 6e 64 20 tic output,.and
8620: 77 69 6c 6c 20 61 6c 73 6f 20 66 6f 72 63 65 20 will also force
8630: 74 68 65 20 76 65 72 69 66 79 20 6d 65 74 68 6f the verify metho
8640: 64 20 69 6e 20 5b 63 6d 64 20 74 6c 73 3a 3a 63 d in [cmd tls::c
8650: 61 6c 6c 62 61 63 6b 5d 20 74 6f 20 61 63 63 65 allback] to acce
8660: 70 74 20 74 68 65 0a 63 65 72 74 69 66 69 63 61 pt the.certifica
8670: 74 65 2c 20 65 76 65 6e 20 69 66 20 69 74 20 69 te, even if it i
8680: 73 20 69 6e 76 61 6c 69 64 20 77 68 65 6e 20 74 s invalid when t
8690: 68 65 20 5b 6f 70 74 69 6f 6e 20 2d 76 61 6c 69 he [option -vali
86a0: 64 61 74 65 63 6f 6d 6d 61 6e 64 5d 0a 6f 70 74 datecommand].opt
86b0: 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 5b 63 ion is set to [c
86c0: 6d 64 20 74 6c 73 3a 3a 76 61 6c 69 64 61 74 65 md tls::validate
86d0: 5f 63 6f 6d 6d 61 6e 64 5d 2e 0a 0a 5b 70 61 72 _command]...[par
86e0: 61 5d 0a 0a 5b 65 6d 70 68 20 22 54 68 65 20 75 a]..[emph "The u
86f0: 73 65 20 6f 66 20 74 68 65 20 76 61 72 69 61 62 se of the variab
8700: 6c 65 20 5b 76 61 72 20 74 6c 73 3a 3a 64 65 62 le [var tls::deb
8710: 75 67 5d 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d ug] is not recom
8720: 6d 65 6e 64 65 64 2e 0a 49 74 20 6d 61 79 20 62 mended..It may b
8730: 65 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 66 e removed from f
8740: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 22 uture releases."
8750: 5d 0a 0a 5b 73 65 63 74 69 6f 6e 20 22 48 54 54 ]..[section "HTT
8760: 50 20 50 61 63 6b 61 67 65 20 45 78 61 6d 70 6c P Package Exampl
8770: 65 73 22 5d 0a 0a 54 68 65 20 66 6f 6c 6c 6f 77 es"]..The follow
8780: 69 6e 67 20 61 72 65 20 65 78 61 6d 70 6c 65 20 ing are example
8790: 73 63 72 69 70 74 73 20 74 6f 20 64 6f 77 6e 6c scripts to downl
87a0: 6f 61 64 20 61 20 77 65 62 70 61 67 65 20 61 6e oad a webpage an
87b0: 64 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 d file using the
87c0: 0a 68 74 74 70 20 70 61 63 6b 61 67 65 2e 20 53 .http package. S
87d0: 65 65 20 5b 73 65 63 74 72 65 66 20 22 43 65 72 ee [sectref "Cer
87e0: 74 69 66 69 63 61 74 65 20 56 61 6c 69 64 61 74 tificate Validat
87f0: 69 6f 6e 22 5d 20 66 6f 72 20 77 68 65 74 68 65 ion"] for whethe
8800: 72 20 74 68 65 0a 5b 6f 70 74 69 6f 6e 20 2d 63 r the.[option -c
8810: 61 64 69 72 5d 2c 20 5b 6f 70 74 69 6f 6e 20 2d adir], [option -
8820: 63 61 66 69 6c 65 5d 2c 20 61 6e 64 20 5b 6f 70 cafile], and [op
8830: 74 69 6f 6e 20 2d 63 61 73 74 6f 72 65 5d 20 6f tion -castore] o
8840: 70 74 69 6f 6e 73 20 61 72 65 20 61 6c 73 6f 0a ptions are also.
8850: 6e 65 65 64 65 64 2e 20 53 65 65 20 74 68 65 20 needed. See the
8860: 64 65 6d 6f 73 20 64 69 72 65 63 74 6f 72 79 20 demos directory
8870: 66 6f 72 20 6d 6f 72 65 20 65 78 61 6d 70 6c 65 for more example
8880: 20 73 63 72 69 70 74 73 2e 0a 0a 5b 70 61 72 61 scripts...[para
8890: 5d 0a 0a 45 78 61 6d 70 6c 65 20 23 31 3a 20 44 ]..Example #1: D
88a0: 6f 77 6e 6c 6f 61 64 20 61 20 77 65 62 20 70 61 ownload a web pa
88b0: 67 65 0a 0a 5b 65 78 61 6d 70 6c 65 20 7b 0a 0a ge..[example {..
88c0: 70 61 63 6b 61 67 65 20 72 65 71 75 69 72 65 20 package require
88d0: 68 74 74 70 0a 70 61 63 6b 61 67 65 20 72 65 71 http.package req
88e0: 75 69 72 65 20 74 6c 73 0a 0a 73 65 74 20 75 72 uire tls..set ur
88f0: 6c 20 22 68 74 74 70 73 3a 2f 2f 77 77 77 2e 74 l "https://www.t
8900: 63 6c 2e 74 6b 2f 22 0a 68 74 74 70 3a 3a 72 65 cl.tk/".http::re
8910: 67 69 73 74 65 72 20 68 74 74 70 73 20 34 34 33 gister https 443
8920: 20 5b 6c 69 73 74 20 3a 3a 74 6c 73 3a 3a 73 6f [list ::tls::so
8930: 63 6b 65 74 20 2d 61 75 74 6f 73 65 72 76 65 72 cket -autoserver
8940: 6e 61 6d 65 20 31 20 2d 72 65 71 75 69 72 65 20 name 1 -require
8950: 31 5d 0a 0a 23 20 47 65 74 20 55 52 4c 0a 73 65 1]..# Get URL.se
8960: 74 20 74 6f 6b 65 6e 20 5b 68 74 74 70 3a 3a 67 t token [http::g
8970: 65 74 75 72 6c 20 24 75 72 6c 5d 0a 0a 23 20 43 eturl $url]..# C
8980: 68 65 63 6b 20 66 6f 72 20 65 72 72 6f 72 0a 69 heck for error.i
8990: 66 20 7b 5b 68 74 74 70 3a 3a 73 74 61 74 75 73 f {[http::status
89a0: 20 24 74 6f 6b 65 6e 5d 20 6e 65 20 22 6f 6b 22 $token] ne "ok"
89b0: 7d 20 7b 0a 20 20 20 20 70 75 74 73 20 5b 66 6f } {. puts [fo
89c0: 72 6d 61 74 20 22 45 72 72 6f 72 20 25 73 22 20 rmat "Error %s"
89d0: 5b 68 74 74 70 3a 3a 73 74 61 74 75 73 20 24 74 [http::status $t
89e0: 6f 6b 65 6e 5d 5d 0a 7d 0a 0a 23 20 53 61 76 65 oken]].}..# Save
89f0: 20 77 65 62 20 70 61 67 65 20 74 6f 20 66 69 6c web page to fil
8a00: 65 0a 73 65 74 20 63 68 20 5b 6f 70 65 6e 20 65 e.set ch [open e
8a10: 78 61 6d 70 6c 65 2e 68 74 6d 6c 20 77 62 5d 0a xample.html wb].
8a20: 70 75 74 73 20 24 63 68 20 5b 68 74 74 70 3a 3a puts $ch [http::
8a30: 64 61 74 61 20 24 74 6f 6b 65 6e 5d 0a 63 6c 6f data $token].clo
8a40: 73 65 20 24 63 68 0a 0a 23 20 43 6c 65 61 6e 75 se $ch..# Cleanu
8a50: 70 0a 3a 3a 68 74 74 70 3a 3a 63 6c 65 61 6e 75 p.::http::cleanu
8a60: 70 20 24 74 6f 6b 65 6e 0a 7d 5d 0a 0a 45 78 61 p $token.}]..Exa
8a70: 6d 70 6c 65 20 23 32 3a 20 44 6f 77 6e 6c 6f 61 mple #2: Downloa
8a80: 64 20 61 20 66 69 6c 65 0a 0a 5b 65 78 61 6d 70 d a file..[examp
8a90: 6c 65 20 7b 0a 0a 70 61 63 6b 61 67 65 20 72 65 le {..package re
8aa0: 71 75 69 72 65 20 68 74 74 70 0a 70 61 63 6b 61 quire http.packa
8ab0: 67 65 20 72 65 71 75 69 72 65 20 74 6c 73 0a 0a ge require tls..
8ac0: 73 65 74 20 75 72 6c 20 22 68 74 74 70 73 3a 2f set url "https:/
8ad0: 2f 77 69 6b 69 2e 74 63 6c 2d 6c 61 6e 67 2e 6f /wiki.tcl-lang.o
8ae0: 72 67 2f 73 69 74 65 6d 61 70 2e 78 6d 6c 22 0a rg/sitemap.xml".
8af0: 68 74 74 70 3a 3a 72 65 67 69 73 74 65 72 20 68 http::register h
8b00: 74 74 70 73 20 34 34 33 20 5b 6c 69 73 74 20 3a ttps 443 [list :
8b10: 3a 74 6c 73 3a 3a 73 6f 63 6b 65 74 20 2d 61 75 :tls::socket -au
8b20: 74 6f 73 65 72 76 65 72 6e 61 6d 65 20 31 20 2d toservername 1 -
8b30: 72 65 71 75 69 72 65 20 31 5d 0a 0a 23 20 4f 70 require 1]..# Op
8b40: 65 6e 20 6f 75 74 70 75 74 20 66 69 6c 65 0a 73 en output file.s
8b50: 65 74 20 66 69 6c 65 6e 61 6d 65 20 5b 66 69 6c et filename [fil
8b60: 65 20 74 61 69 6c 20 24 75 72 6c 5d 0a 73 65 74 e tail $url].set
8b70: 20 63 68 20 5b 6f 70 65 6e 20 24 66 69 6c 65 6e ch [open $filen
8b80: 61 6d 65 20 77 62 5d 0a 0a 23 20 47 65 74 20 66 ame wb]..# Get f
8b90: 69 6c 65 0a 73 65 74 20 74 6f 6b 65 6e 20 5b 3a ile.set token [:
8ba0: 3a 68 74 74 70 3a 3a 67 65 74 75 72 6c 20 24 75 :http::geturl $u
8bb0: 72 6c 20 2d 62 6c 6f 63 6b 73 69 7a 65 20 36 35 rl -blocksize 65
8bc0: 35 33 36 20 2d 63 68 61 6e 6e 65 6c 20 24 63 68 536 -channel $ch
8bd0: 5d 0a 0a 23 20 43 68 65 63 6b 20 66 6f 72 20 65 ]..# Check for e
8be0: 72 72 6f 72 0a 69 66 20 7b 5b 68 74 74 70 3a 3a rror.if {[http::
8bf0: 73 74 61 74 75 73 20 24 74 6f 6b 65 6e 5d 20 6e status $token] n
8c00: 65 20 22 6f 6b 22 7d 20 7b 0a 20 20 20 20 70 75 e "ok"} {. pu
8c10: 74 73 20 5b 66 6f 72 6d 61 74 20 22 45 72 72 6f ts [format "Erro
8c20: 72 20 25 73 22 20 5b 68 74 74 70 3a 3a 73 74 61 r %s" [http::sta
8c30: 74 75 73 20 24 74 6f 6b 65 6e 5d 5d 0a 7d 0a 0a tus $token]].}..
8c40: 23 20 43 6c 65 61 6e 75 70 0a 63 6c 6f 73 65 20 # Cleanup.close
8c50: 24 63 68 0a 3a 3a 68 74 74 70 3a 3a 63 6c 65 61 $ch.::http::clea
8c60: 6e 75 70 20 24 74 6f 6b 65 6e 0a 7d 5d 0a 0a 5b nup $token.}]..[
8c70: 73 65 63 74 69 6f 6e 20 22 53 70 65 63 69 61 6c section "Special
8c80: 20 43 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 22 Considerations"
8c90: 5d 0a 0a 54 68 65 20 63 61 70 61 62 69 6c 69 74 ]..The capabilit
8ca0: 69 65 73 20 6f 66 20 74 68 69 73 20 70 61 63 6b ies of this pack
8cb0: 61 67 65 20 63 61 6e 20 76 61 72 79 20 65 6e 6f age can vary eno
8cc0: 72 6d 6f 75 73 6c 79 20 62 61 73 65 64 20 75 70 rmously based up
8cd0: 6f 6e 20 68 6f 77 20 74 68 65 0a 6c 69 6e 6b 65 on how the.linke
8ce0: 64 20 74 6f 20 4f 70 65 6e 53 53 4c 20 6c 69 62 d to OpenSSL lib
8cf0: 72 61 72 79 20 77 61 73 20 63 6f 6e 66 69 67 75 rary was configu
8d00: 72 65 64 20 61 6e 64 20 62 75 69 6c 74 2e 20 4e red and built. N
8d10: 65 77 20 76 65 72 73 69 6f 6e 73 20 6d 61 79 20 ew versions may
8d20: 6f 62 73 6f 6c 65 74 65 0a 6f 6c 64 65 72 20 70 obsolete.older p
8d30: 72 6f 74 6f 63 6f 6c 20 76 65 72 73 69 6f 6e 73 rotocol versions
8d40: 2c 20 61 64 64 20 6f 72 20 72 65 6d 6f 76 65 20 , add or remove
8d50: 63 69 70 68 65 72 73 2c 20 63 68 61 6e 67 65 20 ciphers, change
8d60: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 73 2c 20 default values,
8d70: 65 74 63 2e 0a 55 73 65 20 74 68 65 20 5b 63 6d etc..Use the [cm
8d80: 64 20 74 6c 73 3a 3a 70 72 6f 74 6f 63 6f 6c 73 d tls::protocols
8d90: 5d 20 63 6f 6d 6d 61 6e 64 73 20 74 6f 20 6f 62 ] commands to ob
8da0: 74 61 69 6e 20 74 68 65 20 73 75 70 70 6f 72 74 tain the support
8db0: 65 64 0a 70 72 6f 74 6f 63 6f 6c 20 76 65 72 73 ed.protocol vers
8dc0: 69 6f 6e 73 2e 0a 0a 5b 6d 61 6e 70 61 67 65 5f ions...[manpage_
8dd0: 65 6e 64 5d 0a end].