Overview
Comment: | Split doc file into TLS and cryptography files. Moved digest functions to cryptography.html doc file. Added schema file from TCL man pages. Updated TLS doc file. |
---|---|
Downloads: | Tarball | ZIP archive | SQL archive |
Timelines: | family | ancestors | descendants | both | crypto |
Files: | files | file ages | folders |
SHA3-256: |
b5b7a4964e85c97bb4361ee632907113 |
User & Date: | bohagan on 2023-11-26 02:15:24 |
Other Links: | branch diff | manifest | tags |
Context
2023-11-27
| ||
02:39 | Code Cleanup to use switch statements check-in: 24e26c8844 user: bohagan tags: crypto | |
2023-11-26
| ||
02:15 | Split doc file into TLS and cryptography files. Moved digest functions to cryptography.html doc file. Added schema file from TCL man pages. Updated TLS doc file. check-in: b5b7a4964e user: bohagan tags: crypto | |
2023-11-25
| ||
05:23 | Split get digest, cipher, key, and mac ids into separate functions. Simplified DigestMain to pass Tcl objects to get functions. Pass mac id to functions. check-in: 0aae4d5b6f user: bohagan tags: crypto | |
Changes
Added doc/cryptography.html version [d060a163a5].
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 | <!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="2023 Brian O'Hagan"> <title>The Tcl Cryptography Package</title> <link rel="stylesheet" href="docs.css" type="text/css" media="all"> </head> <body class="vsc-initialized"> <h2>Tcl Cryptography Documentation</h2> <dl> <dd><a href="#NAME">NAME</a> <dl><dd><b>tls</b> - binding to <b>OpenSSL</b> toolkit.</dd></dl> </dd> <dd><a href="#DESCRIPTION">DESCRIPTION</a> </dd> <dd><a href="#SYNOPSIS">SYNOPSIS</a> </dd> <dd><dl> <dd><b>package require Tcl</b> <em>?8.5-?</em></dd> <dd><b>package require tls</b></dd> <dt> </dt> <dd><b>tls::cipher</b> <em>name</em></dd> <dd><b>tls::ciphers</b> <em>?protocol? ?verbose? ?supported?</em></dd> <dd><b>tls::digests</b> <em>?name?</em></dd> <dd><b>tls::macs</b></dd> <dd><b>tls::protocols</b></dd> <dd><b>tls::version</b></dd> <dt> </dt> <dd><b>tls::cmac</b> <b>-cipher</b> <em>name</em> <b>-key</b> <em>key ?options?</em></dd> <dd><b>tls::hmac</b> <b>-digest</b> <em>name</em> <b>-key</b> <em>key ?options?</em></dd> <dd><b>tls::md</b> <b>-digest</b> <em>name ?options?</em></dd> <dd><b>tls::md4</b> <em>data</em></dd> <dd><b>tls::md5</b> <em>data</em></dd> <dd><b>tls::sha1</b> <em>data</em></dd> <dd><b>tls::sha256</b> <em>data</em></dd> <dd><b>tls::sha512</b> <em>data</em></dd> <dd><b>tls::unstack</b> <em>channelId</em></dd> </dl> </dd> <dd><a href="#OPTIONS">OPTIONS</a></dd> <dd><a href="#COMMANDS">COMMANDS</a></dd> <dd><a href="#GLOSSARY">GLOSSARY</a> </dd> <dd><a href="#EXAMPLES">EXAMPLES</a></dd> <dd><a href="#SPECIAL">SPECIAL CONSIDERATIONS</a></dd> </dl> <br> <h3><a name="NAME">NAME</a></h3> <p><strong>tls</strong> - binding to <strong>OpenSSL</strong> toolkit.</p> <h3><a name="DESCRIPTION">DESCRIPTION</a></h3> <p>This extension provides a generic interface to the <a href="http://www.openssl.org/">OpenSSL</a> cryptography functions. The provided commands can be used to ensure the confidentiality, authenticity, and integrity of messages and data.</p> <br> <h3><a name="SYNOPSIS">SYNOPSIS</a></h3> <p><b>package require Tcl 8.5-</b><br> <b>package require tls</b><br> <br> <a href="#tls::cipher"><b>tls::cipher</b> <i>name</i></a><br> <a href="#tls::ciphers"><b>tls::ciphers</b> <i>?protocol? ?verbose? ?supported?</i></a><br> <a href="#tls::digests"><b>tls::digests</b> <i>?name?</i></a><br> <a href="#tls::macs"><b>tls::macs</b></a><br> <a href="#tls::protocols"><b>tls::protocols</b></a><br> <a href="#tls::version"><b>tls::version</b></a><br> <br> <a href="#tls::cmac"><b>tls::cmac</b> <b>-cipher</b> <i>name</i> <b>-key</b> <i>key ?options?</i></a><br> <a href="#tls::hmac"><b>tls::hmac</b> <b>-digest</b> <i>name</i> <b>-key</b> <i>key ?options?</i></a><br> <a href="#tls::md"><b>tls::md</b> <b>-digest</b> <i>name ?options?</i></a><br> <a href="#tls::md4"><b>tls::md4</b> <i>data</i></a><br> <a href="#tls::md5"><b>tls::md5</b> <i>data</i></a><br> <a href="#tls::sha1"><b>tls::sha1</b> <i>data</i></a><br> <a href="#tls::sha256"><b>tls::sha256</b> <i>data</i></a><br> <a href="#tls::sha512"><b>tls::sha512</b> <i>data</i></a><br> <a href="#tls::unstack"><b>tls::unstack</b> <i>channelId</i></a><br> </p> <br> <h3><a name="OPTIONS">OPTIONS</a></h3> <p>The following options are used by the cryptography commands.</p> <br> <h4>Cryptographic Options</h4> <dl> <dt><a name="-cipher"><strong>-cipher</strong> <em>name</em></a></dt> <dd>Name of cryptographic cipher to use. Used by the CMAC and GMAC hash algorithms. For CMAC it must be one of AES-128-CBC, AES-192-CBC, AES-256-CBC or DES-EDE3-CBC. For GMAC it should be a GCM mode cipher e.g. AES-128-GCM. See <a href="#tls::ciphers"><b>tls::ciphers</b></a> for the valid values.</dd> </dl> <dl> <dt><a name="-digest"><strong>-digest</strong> <em>name</em></a></dt> <dd>Name of hash function (aka message digest) to use. See <a href="#tls::digests"><b>tls::digests</b></a> for the valid values.</dd> </dl> <dl> <dt><a name="-iterations"><strong>-iterations</strong> <em>count</em></a></dt> <dd>Number (integer) of iterations on the password to use in deriving the encryption key. Default is 10000. Some KDF implementations require an iteration count.</dd> </dl> <dl> <dt><a name="-iv"><strong>-iv</strong> <em>string</em></a></dt> <dd>Initialization vector (IV). Required for GMAC. Cipher modes CBC, CFB, OFB and CTR all need an initialization vector (IV) while ECB mode does not. A new, random IV should be created for each use. Think of the IV as a nonce (number used once), it's public but random and unpredictable.</dd> </dl> <dl> <dt><a name="-key"><strong>-key</strong> <em>string</em></a></dt> <dd>Encryption key to use for cryptography function. Can be a binary or text string. Longer keys provide better protection. Used by HMAC, some CMAC, and some KDF implementations. Some functions require key length must conform to <b>key_length</b> size.</dd> </dl> <dl> <dt><a name="-mac"><strong>-mac</strong> <em>name</em></a></dt> <dd>Name of Message Authentication Code (MAC) to use. See <a href="#tls::mac"><b>tls::macs</b></a> for the valid values.</dd> </dl> <dl> <dt><a name="-password"><strong>-password</strong> <em>string</em></a></dt> <dd>Password to use for some KDF functions.</dd> </dl> <dl> <dt><a name="-properties"><strong>-properties</strong> <em>list</em></a></dt> <dd>List of additional properties to pass to cryptography function.</dd> </dl> <dl> <dt><a name="-salt"><strong>-salt</strong> <em>string</em></a></dt> <dd>Specifies salt value to use when encrypting data. Default is to use a randomly generated value. This option is used by BLAKE2 MAC and some KDF implementations use a non-secret unique cryptographic salt.</dd> </dl> <dl> <dt><a name="-size"><strong>-size</strong> <em>number</em></a></dt> <dd>Set the output hash size in bytes. Used by KMAC128 or KMAC256 to specify an output length. The default sizes are 32 or 64 bytes respectively.</dd> </dl> <dl> <dt><a name="-xof"><strong>-xof</strong> <em>boolean</em></a></dt> <dd>Set whether to use XOF. This option is used by KMAC.</dd> </dl> <br> <h4>Input/Output Options</h4> <dl> <dt><a name="-chan"><strong>-chan</strong> <em>channelId</em></a></dt> <dt><a name="-chan"><strong>-channel</strong> <em>channelId</em></a></dt> <dd>Add the cryptographic transformation on top of channel <em>channelId</em>. Automatically sets channel to binary mode. Works like <b>chan push</b> to create a stacked channel. If the command <b>fileevent</b> is to be used for channel event monitoring, all channels in the stack should be set to non-blocking mode. If not, the system may hang while waiting for data. When done, use either the close command or <a href="#tls::unstack"><strong>tls::unstack</strong></a> to remove the transform from the channel. Additional transforms cannot be added to channel. Example code:</dd></dl> <blockquote><code> set ch [open test_file.txt rb]<br> ::tls::digest -digest sha256 -chan $ch<br> while {![eof $ch]} {set md [read $ch 4096]}<br> close $ch<br> puts $md </code></blockquote> <dl> <dt><a name="-command"><strong>-command</strong> <em>cmdName</em></a></dt> <dd>Create and return <em>cmdName</em> which is used to incrementally add data to a cryptographic function. To add data to the function, call "<em>cmdName</em> <b>update</b> <em>data</em>", where <em>data</em> is the data to add. When done, call "<em>cmdName</em> <b>finalize</b>" to return the resulting value and delete <em>cmdName</em>. Example code:</dd></dl> <blockquote><code> set cmd [::tls::digest -digest sha256 -command ::tls::temp]<br> $cmd update "Some data. "<br> $cmd update "More data."<br> set md [$cmd finalize]<br> puts $md </code></blockquote> <dl> <dt><a name="-data"><strong>-data</strong> <em>string</em></a></dt> <dd>Perform the cryptographic function on <em>data</em> and return the result. Example code:</dd></dl> <blockquote><code> set md [::tls::digest sha256 "Some example data."]<br> puts $md </code></blockquote> <dl> <dt><a name="-file"><strong>-file</strong> <em>filename</em></a></dt> <dt><a name="-file"><strong>-filename</strong> <em>filename</em></a></dt> <dd>Perform the cryptographic function on file <em>filename</em> and return the result. This operation will open file, read the file data, close the file, and return the result using the TCL APIs, so VFS files are supported. Example code:</dd></dl> <blockquote><code> set md [::tls::digest -digest sha256 -file test_file.txt]<br> puts $md </code></blockquote> <dl> <dt><a name="-infile"><strong>-infile</strong> <em>filename</em></a></dt> <dd>Specifies the file to use as data input source.</dd></dl> <dl> <dt><a name="-outfile"><strong>-outfile</strong> <em>filename</em></a></dt> <dd>Specifies the file to send the results to.</dd></dl> <dl> <dt><a name="-keyfile"><strong>-keyfile</strong> <em>filename</em></a></dt> <dd>Specifies the file to get the encryption key from.</dd></dl> <br> <h4>Format Options</h4> <dl> <dt><a name="-base64"><strong>-base64</strong></a></dt> <dd>Base64 encode data after encryption or decode before decryption.</dd> </dl> <dl> <dt><a name="-bin"><strong>-bin</strong></a></dt> <dt><a name="-bin"><strong>-binary</strong></a></dt> <dd>Output result of function as a binary string.</dd> </dl> <dl> <dt><a name="-hex"><strong>-hex</strong></a></dt> <dt><a name="-hex"><strong>-hexadecimal</strong></a></dt> <dd>Output result of function as a hexadecimal string. This is the default option unless otherwise specified.</dd> </dl> <br> <h3><a name="COMMANDS">COMMANDS</a></h3> <p>The following commands provide access to the OpenSSL cryptography functions.</p> <dl> <h4>Info Commands</h4> <dt><a name="tls::cipher"><strong>tls::cipher</strong> <em>name</em></a></dt> <dd>Return a list of property names and values describing cipher <i>name</i>. Properties include name, description, block_size, key_length, iv_length, type, and mode list.</dd> <dt><a name="tls::ciphers"><strong>tls::ciphers</strong> <em>?protocol? ?verbose? ?supported?</em></a></dt> <dd>Without any args, returns a list of all symmetric ciphers for use with the <a href="#-cipher"><b>-cipher</b></a> option. With <em>protocol</em>, only the ciphers supported for that protocol are returned. See <b>tls::protocols</b> command for the supported protocols. If <em>verbose</em> is specified as true then a verbose, human readable list is returned with additional information on the cipher. If <em>supported</em> is specified as true, then only the ciphers supported for protocol will be listed.</dd> <dt><a name="tls::digests"><strong>tls::digests</strong> <em>?name?</em></a></dt> <dd>Without <em>name</em>, returns a list of the supported message digests (aka hash algorithms) for use with the <a href="#-digest"><b>-digest</b></a> option. With <em>name</em>, returns a list of property names and values describing message digest <i>name</i>. Properties include name, description, size, block_size, type, and flags list.</dd> <dt><a name="tls::kdfs"><strong>tls::kdfs</strong></a></dt> <dd>Returns a list of the available Key Derivation Function (KDF) algorithms.</dd> <dt><a name="tls::macs"><strong>tls::macs</strong></a></dt> <dd>Returns a list of the available Message Authentication Codes (MAC) for use with the <a href="#-key"><b>-key</b></a> option.</dd> <dt><a name="tls::protocols"><strong>tls::protocols</strong></a></dt> <dd>Returns a list of supported protocols. Valid values are: <b>ssl2</b>, <b>ssl3</b>, <b>tls1</b>, <b>tls1.1</b>, <b>tls1.2</b>, and <b>tls1.3</b>. Exact list depends on OpenSSL version and compile time flags.</dd> <dt><a name="tls::version"><strong>tls::version</strong></a></dt> <dd>Returns the OpenSSL version string.</dd> <br> <h4>Message Digest (MD) and Message Authentication Code (MAC) Commands</h4> <dt><a name="tls::cmac"><strong>tls::cmac</strong> <em>?</em><b>-cipher</b><em>? name</em> <b>-key</b> <em>key ?</em><b>-bin</b>|<b>-hex</b><em>? [</em><b>-file</b> <em>filename | </em><b>-command</b> <em>cmdName | </em><b>-chan</b> <em>channelId | ?</em><b>-data</b><em>? data]</em></a></dt> <dd>Calculate the Cipher-based Message Authentication Code (CMAC) where <em>key</em> is a shared key and output the result per the I/O options in the specified format. MACs are used to ensure authenticity and the integrity of data. See <a href="#OPTIONS"><b>options</b></a> for usage info. Option <b>-key</b> is only used for some ciphers.</dd> <dt><a name="tls::hmac"><strong>tls::hmac</strong> <em>?</em><b>-digest</b><em>? name</em> <b>-key</b> <em>key ?</em><b>-bin</b>|<b>-hex</b><em>? [</em><b>-file</b> <em>filename | </em><b>-command</b> <em>cmdName | </em><b>-chan</b> <em>channelId | ?</em><b>-data</b><em>? data]</em></a></dt> <dd>Calculate the Hash-based Message Authentication Code (HMAC) where <em>key</em> is a shared secret key and output the result per the I/O options in the specified format. The cryptographic strength depends upon the size of the key and the security of the hash function used. See <a href="#OPTIONS"><b>options</b></a> for usage info.</dd> <dt><a name="tls::mac"><strong>tls::mac</strong> <em>?</em><b>-mac</b><em>? name</em> <b>-cipher</b> <em>name</em> <b>-digest</b> <em>name</em> <b>-key</b> <em>key ?</em> <b>-bin</b>|<b>-hex</b><em>? [</em><b>-file</b> <em>filename | </em><b>-command</b> <em>cmdName | </em><b>-chan</b> <em>channelId | ?</em><b>-data</b><em>? data]</em></a></dt> <dd>(OpenSSL 3.0+) Calculate the Message Authentication Code (MAC) where <em>key</em> is a shared key and output the result per the I/O options in the specified format. MACs are used to ensure authenticity and the integrity of data. See <a href="#OPTIONS"><b>options</b></a> for usage info.</dd> <dt><a name="tls::md"><strong>tls::md</strong> <em>?</em><b>-digest</b><em>? name ?</em><b>-bin</b>|<b>-hex</b><em>? [</em><b>-file</b> <em>filename | </em><b>-command</b> <em>cmdName | </em><b>-chan</b> <em>channelId | ?</em><b>-data</b><em>? data]</em></a></dt> <dd>Calculate the message digest (MD) using hash function (aka message digest) <em>name</em> and output the result per the I/O options in the specified format. MDs are used to ensure the integrity of data. See <a href="#OPTIONS"><b>options</b></a> for usage info.</dd> <dt><a name="tls::md4"><strong>tls::md4</strong> <em>data</em></a></dt> <dd>Returns the MD4 message-digest for <em>data</em> as a hex string.</dd> <dt><a name="tls::md5"><strong>tls::md5</strong> <em>data</em></a></dt> <dd>Returns the MD5 message-digest for <em>data</em> as a hex string.</dd> <dt><a name="tls::sha1"><strong>tls::sha1</strong> <em>data</em></a></dt> <dd>Returns the SHA1 secure hash algorithm digest for <em>data</em> as a hex string.</dd> <dt><a name="tls::sha256"><strong>tls::sha256</strong> <em>data</em></a></dt> <dd>Returns the SHA-2 SHA256 secure hash algorithm digest for <em>data</em> as a hex string.</dd> <dt><a name="tls::sha512"><strong>tls::sha512</strong> <em>data</em></a></dt> <dd>Returns the SHA-2 SHA512 secure hash algorithm digest for <em>data</em> as a hex string.</dd> <dt><a name="tls::unstack"><strong>tls::unstack</strong> <em>channelId</em></a></dt> <dd>Removes the top level cryptographic transform from channel <em>channelId</em>.</dd> </dl> <br> <h3><a name="GLOSSARY">GLOSSARY</a></h3> <p>The following is a list of the terminology used in this package along with brief definitions. For more details, please consult with the OpenSSL documentation.</p> <br> <h3><a name="EXAMPLES">EXAMPLES</a></h3> <p>TBS</p> <pre><code> package require http package require tls http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs] set tok [http::geturl https://www.tcl.tk/] </code></pre> <br> <h3><a name="SPECIAL">SPECIAL CONSIDERATIONS</a></h3> <p>The capabilities of this package can vary enormously based upon how your OpenSSL library was configured and built. New versions may obsolete older ciphers, digests, MACs, etc. or change default values. Use the info commands to obtain the supported values.</p> <br> <pre> Copyright © 2023 Brian O'Hagan. </pre> </body> </html> |
Added doc/docs.css version [0ab4787813].
> | 1 | body,div,p,th,td,li,dd,ul,ol,dl,dt,blockquote{font-family:Verdana,sans-serif}pre,code{font-family:courier new,Courier,monospace}pre{background-color:#f6fcec;border-top:1px solid #6a6a6a;border-bottom:1px solid #6a6a6a;padding:1em;overflow:auto}body{background-color:#fff;font-size:12px;line-height:1.25;letter-spacing:.2px;padding-left:.5em}h1,h2,h3,h4{font-family:Georgia,serif;padding-left:1em;margin-top:1em}h1{font-size:18px;color:#11577b;border-bottom:1px dotted #11577b;margin-top:0}h2{font-size:14px;color:#11577b;background-color:#c5dce8;padding-left:1em;border:1px solid #6a6a6a}h3,h4{color:#1674a4;background-color:#e8f2f6;border-bottom:1px dotted #11577b;border-top:1px dotted #11577b}h3{font-size:12px}h4{font-size:11px}.keylist dt,.arguments dt{width:20em;float:left;padding:2px;border-top:1px solid #999}.keylist dt{font-weight:700}.keylist dd,.arguments dd{margin-left:20em;padding:2px;border-top:1px solid #999}.copy{background-color:#f6fcfc;white-space:pre;font-size:80%;border-top:1px solid #6a6a6a;margin-top:2em}.tablecell{font-size:12px;padding-left:.5em;padding-right:.5em} |
Modified doc/tls.html from [b95229bb9c] to [12b4e9e9d7].
|
| < < | | | > > | > | > | | | | < < < < < < < < < < < < < | | < < < < < < < < < < < < < | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | <!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="Copyright" content="1999 Matt Newman / 2004 Starfish Systems"> <title>TLS (SSL) TCL Commands</title> <link rel="stylesheet" href="docs.css" type="text/css" media="all"> </head> <body class="vsc-initialized"> <h2>Tcl Tls Extension Documentation</h2> <dl> <dd><a href="#NAME">NAME</a> <dl> <dd><b>tls</b> - binding to <b>OpenSSL</b> library for socket and I/O channel communications.</dd> </dl> </dd> <dd><a href="#SYNOPSIS">SYNOPSIS</a> </dd> <dd><dl> <dd><b>package require Tcl</b> <em>?8.5?</em></dd> <dd><b>package require tls</b></dd> <dt> </dt> <dd><b>tls::init</b> <em>?options?</em> </dd> <dd><b>tls::socket</b> <em>?options? host port</em></dd> <dd><b>tls::socket</b> <em>?-server command? ?options? port</em></dd> <dd><b>tls::handshake</b> <em> channel</em></dd> <dd><b>tls::status</b> <em>?-local? channel</em></dd> <dd><b>tls::connection</b> <em>channel</em></dd> <dd><b>tls::import</b> <em>channel ?options?</em></dd> <dd><b>tls::unimport</b> <em>channel</em></dd> <dt> </dt> <dd><b>tls::protocols</b></dd> <dd><b>tls::version</b></dd> </dl> </dd> <dd><a href="#COMMANDS">COMMANDS</a></dd> <dd><a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a></dd> <dd><a href="#HTTPS EXAMPLE">HTTPS EXAMPLE</a></dd> <dd><a href="#SEE ALSO">SPECIAL CONSIDERATIONS</a></dd> <dd><a href="#SEE ALSO">SEE ALSO</a></dd> </dl> <hr> <h3><a name="NAME">NAME</a></h3> <p><strong>tls</strong> - binding to <strong>OpenSSL</strong> library for socket and I/O channel communications.</p> <h3><a name="SYNOPSIS">SYNOPSIS</a></h3> <p><b>package require Tcl 8.5</b><br> <b>package require tls</b><br> <br> <a href="#tls::init"><b>tls::init</b> <i>?options?</i></a><br> <a href="#tls::socket"><b>tls::socket</b> <i>?options? host port</i><br> <a href="#tls::socket"><b>tls::socket</b> <i>?-server command? ?options? port</i></a><br> <a href="#tls::status"><b>tls::status</b> <i>?-local? channel</i></a><br> <a href="#tls::connection"><b>tls::connection</b> <i>channel</i></a><br> <a href="#tls::handshake"><b>tls::handshake</b> <i>channel</i></a><br> <a href="#tls::import"><b>tls::import</b> <i>channel ?options?</i></a><br> <a href="#tls::unimport"><b>tls::unimport</b> <i>channel</i></a><br> <br> <a href="#tls::protocols"><b>tls::protocols</b></a><br> <a href="#tls::version"><b>tls::version</b></a><br> </p> <h3><a name="DESCRIPTION">DESCRIPTION</a></h3> <p>This extension provides a generic binding to <a href="http://www.openssl.org/">OpenSSL</a>, utilizing the <strong>Tcl_StackChannel</strong> |
︙ | ︙ | |||
121 122 123 124 125 126 127 | <dt> </dt> <dt><a name="tls::socket"><b>tls::socket </b><em>?options? host port</em></a></dt> <dt><b>tls::socket</b><em> ?-server command? ?options? port</em></dt> <dd>This is a helper function that utilizes the underlying commands (<strong>tls::import</strong>). It behaves exactly the same as the native Tcl <strong>socket</strong> | | | | | | | | 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | <dt> </dt> <dt><a name="tls::socket"><b>tls::socket </b><em>?options? host port</em></a></dt> <dt><b>tls::socket</b><em> ?-server command? ?options? port</em></dt> <dd>This is a helper function that utilizes the underlying commands (<strong>tls::import</strong>). It behaves exactly the same as the native Tcl <strong>socket</strong> command except the options can also include any of the applicable <a href="#tls::import"><strong>tls:import</strong></a> options with one additional option:</dd> <blockquote> <dl> <dt><strong>-autoservername</strong> <em>bool</em></dt> <dd>Automatically set the -servername argument to the <em>host</em> argument (default is <em>false</em>).</dd> </dl> </blockquote> <dt><a name="tls::import"><b>tls::import </b><i>channel ?options?</i></a></dt> <dd>Add SSL/TLS encryption to a regular Tcl channel. It need not be a socket, but must provide bi-directional flow. Also set session parameters for SSL handshake.</dd> <blockquote> <dl> <dt><strong>-alpn</strong> <em>list</em></dt> <dd>List of protocols to offer during Application-Layer Protocol Negotiation (ALPN). For example: <em>h2</em> and <em>http/1.1</em>, but not <em>h3</em> or <em>quic</em>.</dd> |
︙ | ︙ | |||
159 160 161 162 163 164 165 | <dt><strong>-certfile</strong> <em>filename</em></dt> <dd>Specify the filename with the certificate to use.</dd> <dt><strong>-cert</strong> <em>filename</em></dt> <dd>Specify the contents of a certificate to use, as a DER encoded binary value (X.509 DER).</dd> <dt><strong>-cipher</strong> <em>string</em></dt> <dd>List of ciphers to use. String is a colon (":") separated list | | | | | > > | | > | | | < | | > | | | > | | | | | | < | 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 | <dt><strong>-certfile</strong> <em>filename</em></dt> <dd>Specify the filename with the certificate to use.</dd> <dt><strong>-cert</strong> <em>filename</em></dt> <dd>Specify the contents of a certificate to use, as a DER encoded binary value (X.509 DER).</dd> <dt><strong>-cipher</strong> <em>string</em></dt> <dd>List of ciphers to use. String is a colon (":") separated list of ciphers. Ciphers can be combined using the <b>+</b> character. Prefixes can be used to permanently remove ("!"), delete ("-"), or move a cypher to the end of the list ("+"). Keywords <b>@STRENGTH</b> (sort by algorithm key length), <b>@SECLEVEL=</b><i>n</i> (set security level to n), and <b>DEFAULT</b> (use default cipher list, at start only) can also be specified. See OpenSSL documentation for the full list of valid values. (TLS 1.2 and earlier only)</dd> <dt><strong>-ciphersuites</strong> <em>string</em></dt> <dd>List of cipher suites to use. String is a colon (":") separated list of cipher suite names. (TLS 1.3 only)</dd> <dt><strong>-command</strong> <em>callback</em></dt> <dd>Callback command to invoke at several points during the handshake. This is used to pass errors and tracing information, and it can allow Tcl scripts to perform their own certificate validation in place of the default validation provided by OpenSSL. See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a> for further discussion.</dd> <dt><strong>-dhparams </strong><em>filename</em></dt> <dd>Specify the Diffie-Hellman parameters file.</dd> <dt><strong>-keyfile</strong> <em>filename</em></dt> <dd>Specify the private key file. (default is value of -certfile)</dd> <dt><strong>-key</strong> <em>filename</em></dt> <dd>Specify the private key to use as a DER encoded value (PKCS#1 DER)</dd> <dt><strong>-model</strong> <em>channel</em></dt> <dd>Force this channel to share the same <em><strong>SSL_CTX</strong></em> structure as the specified <em>channel</em>, and therefore share callbacks etc.</dd> <dt><strong>-password</strong> <em>callback</em></dt> <dd>Callback command to invoke when OpenSSL needs to obtain a password. Typically used to unlock the private key of a certificate. The callback should return a string which represents the password to be used. See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a> for further discussion.</dd> <dt><strong>-post_handshake</strong> <em>bool</em></dt> <dd>Allow post-handshake ticket updates.</dd> <dt><strong>-request </strong><em>bool</em></dt> <dd>Request a certificate from peer during SSL handshake. (default is <em>true</em>)</dd> <dt><strong>-require</strong> <em>bool</em></dt> <dd>Require a valid certificate from peer during SSL handshake. If this is set to true, then <strong>-request</strong> must also be set to true and a either a -cadir, -cafile, or platform default must be provided in order to validate against. (default is <em>false</em>)</dd> <dt><strong>-security_level</strong> <em>integer</em></dt> <dd>Set security level. Must be 0 to 5. The security level affects the cipher suite encryption algorithms, supported ECC curves, supported signature algorithms, DH parameter sizes, certificate key sizes and signature algorithms. The default is 1. Level 3 and higher disable support for session tickets and only accept cipher suites that provide forward secrecy.</dd> <dt><strong>-server</strong> <em>bool</em></dt> <dd>Set to act as a server and respond with a server handshake when a client connects and provides a client handshake. (default is <em>false</em>)</dd> <dt><strong>-servername</strong> <em>host</em></dt> <dd>Specify server's hostname. Used to set the TLS 'Server Name Indication' (SNI) extension. Set to the expected servername in the server's certificate or one of the subjectAltName alternates.</dd> <dt><strong>-session_id</strong> <em>string</em></dt> <dd>Session id to resume session.</dd> <dt><strong>-ssl2</strong> <em>bool</em></dt> <dd>Enable use of SSL v2. (default is <em>false</em>)</dd> <dt><strong>-ssl3 </strong><em>bool</em></dt> <dd>Enable use of SSL v3. (default is <em>false</em>)</dd> <dt>-<strong>tls1</strong> <em>bool</em></dt> <dd>Enable use of TLS v1. (default is <em>true</em>)</dd> <dt>-<strong>tls1.1</strong> <em>bool</em></dt> <dd>Enable use of TLS v1.1 (default is <em>true</em>)</dd> <dt>-<strong>tls1.2</strong> <em>bool</em></dt> <dd>Enable use of TLS v1.2 (default is <em>true</em>)</dd> <dt>-<strong>tls1.3</strong> <em>bool</em></dt> <dd>Enable use of TLS v1.3 (default is <em>true</em>)</dd> <dt><strong>-validatecommand</strong> <em>callback</em></dt> <dd>Callback command to invoke to verify or validate protocol config parameters during the protocol negotiation phase. See <a href="#CALLBACK OPTIONS">CALLBACK OPTIONS</a> for further discussion.</dd> </dl> </blockquote> <dt><a name="tls::unimport"><b>tls::unimport </b><i>channel</i></a></dt> <dd>Provided for symmetry to <strong>tls::import</strong>, this unstacks the encryption of a regular Tcl channel. An error is thrown if TLS is not the top stacked channel type.</dd> <dt> </dt> <dt><a name="tls::handshake"><strong>tls::handshake</strong> <em>channel</em></a></dt> <dd>Forces handshake to take place, and returns 0 if handshake is still in progress (non-blocking), or 1 if the handshake was successful. If the handshake failed this routine will throw an error.</dd> <dt> </dt> <dt><a name="tls::status"><strong>tls::status</strong> <em>?</em><b>-local</b><em>? channel</em></a></dt> <dd>Returns the current status of an SSL channel. The result is a list of key-value pairs describing the SSL, certificate, and certificate verification status. If the SSL handshake has not yet completed, an empty list is returned. If <b>-local</b> is specified, then the local certificate is used.</dd> <blockquote> <b>SSL Status</b> <dl> <dt><strong>alpn</strong> <em>protocol</em></dt> <dd>The protocol selected after Application-Layer Protocol Negotiation (ALPN).</dd> <dt><strong>cipher</strong> <em>cipher</em></dt> <dd>The current cipher in use between for the channel.</dd> <dt><strong>peername</strong> <em>name</em></dt> <dd>The peername from the certificate.</dd> <dt><strong>protocol</strong> <em>version</em></dt> <dd>The protocol version used for the connection: SSL2, SSL3, TLS1, TLS1.1, TLS1.2, TLS1.3, or unknown.</dd> <dt><strong>sbits</strong> <em>n</em></dt> <dd>The number of bits used for the session key.</dd> |
︙ | ︙ | |||
298 299 300 301 302 303 304 | <dl> <dt><strong>all</strong> <em>string</em></dt> <dd>Dump of all certificate info.</dd> <dt><strong>version</strong> <em>value</em></dt> <dd>The certificate version.</dd> <dt><strong>serialNumber</strong> <em>n</em></dt> | | | 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 | <dl> <dt><strong>all</strong> <em>string</em></dt> <dd>Dump of all certificate info.</dd> <dt><strong>version</strong> <em>value</em></dt> <dd>The certificate version.</dd> <dt><strong>serialNumber</strong> <em>n</em></dt> <dd>The serial number of the certificate as a hex string.</dd> <dt><strong>signature</strong> <em>algorithm</em></dt> <dd>Cipher algorithm used for certificate signature.</dd> <dt><strong>issuer</strong> <em>dn</em></dt> <dd>The distinguished name (DN) of the certificate issuer.</dd> <dt><strong>notBefore</strong> <em>date</em></dt> <dd>The begin date for the validity of the certificate.</dd> <dt><strong>notAfter</strong> <em>date</em></dt> |
︙ | ︙ | |||
322 323 324 325 326 327 328 | <dt><strong>num_extensions</strong> <em>n</em></dt> <dd>Number of certificate extensions.</dd> <dt><strong>extensions</strong> <em>list</em></dt> <dd>List of certificate extension names.</dd> <dt><strong>authorityKeyIdentifier</strong> <em>string</em></dt> <dd>(AKI) Key identifier of the Issuing CA certificate that signed | | | | | | | | | | | | < | 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 | <dt><strong>num_extensions</strong> <em>n</em></dt> <dd>Number of certificate extensions.</dd> <dt><strong>extensions</strong> <em>list</em></dt> <dd>List of certificate extension names.</dd> <dt><strong>authorityKeyIdentifier</strong> <em>string</em></dt> <dd>(AKI) Key identifier of the Issuing CA certificate that signed the SSL certificate as a hex string. This value matches the SKI value of the Intermediate CA certificate.</dd> <dt><strong>subjectKeyIdentifier</strong> <em>string</em></dt> <dd>(SKI) Hash of the public key inside the certificate as a hex string. Used to identify certificates that contain a particular public key.</dd> <dt><strong>subjectAltName</strong> <em>list</em></dt> <dd>List of all of the alternative domain names, sub domains, and IP addresses that are secured by the certificate.</dd> <dt><strong>ocsp</strong> <em>list</em></dt> <dd>List of all Online Certificate Status Protocol (OCSP) URLs.</dd> <dt><strong>certificate</strong> <em>cert</em></dt> <dd>The PEM encoded certificate.</dd> <dt><strong>signatureAlgorithm</strong> <em>algorithm</em></dt> <dd>Cipher algorithm used for the certificate signature.</dd> <dt><strong>signatureValue</strong> <em>string</em></dt> <dd>Certificate signature as a hex string.</dd> <dt><strong>signatureDigest</strong> <em>version</em></dt> <dd>Certificate signing digest as a hex string.</dd> <dt><strong>publicKeyAlgorithm</strong> <em>algorithm</em></dt> <dd>Certificate signature public key algorithm.</dd> <dt><strong>publicKey</strong> <em>string</em></dt> <dd>Certificate signature public key as a hex string.</dd> <dt><strong>bits</strong> <em>n</em></dt> <dd>Number of bits used for certificate signature key.</dd> <dt><strong>self_signed</strong> <em>boolean</em></dt> <dd>Whether the certificate signature is self signed.</dd> <dt><strong>sha1_hash</strong> <em>hash</em></dt> <dd>The SHA1 hash of the certificate as a hex string.</dd> <dt><strong>sha256_hash</strong> <em>hash</em></dt> <dd>The SHA256 hash of the certificate as a hex string.</dd> </dl> </blockquote> <dt><a name="tls::connection"><strong>tls::connection</strong> <em>channel</em></a></dt> <dd>Returns the current connection status of an SSL channel. The result is a list of key-value pairs describing the connection.</dd> <blockquote> <b>SSL Status</b> <dl> <dt><strong>state</strong> <em>state</em></dt> <dd>State of the connection.</dd> <dt><strong>servername</strong> <em>name</em></dt> <dd>The name of the connected to server.</dd> |
︙ | ︙ | |||
404 405 406 407 408 409 410 | <dt><strong>algorithm_bits</strong> <em>n</em></dt> <dd>The number of processed bits used for cipher.</dd> <dt><strong>secret_bits</strong> <em>n</em></dt> <dd>The number of secret bits used for cipher.</dd> <dt><strong>min_version</strong> <em>version</em></dt> <dd>The minimum protocol version for cipher.</dd> <dt><strong>cipher_is_aead</strong> <em>boolean</em></dt> | | | | < < < < < < < < < < < < < < < < < < < < < < < < < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | | 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 | <dt><strong>algorithm_bits</strong> <em>n</em></dt> <dd>The number of processed bits used for cipher.</dd> <dt><strong>secret_bits</strong> <em>n</em></dt> <dd>The number of secret bits used for cipher.</dd> <dt><strong>min_version</strong> <em>version</em></dt> <dd>The minimum protocol version for cipher.</dd> <dt><strong>cipher_is_aead</strong> <em>boolean</em></dt> <dd>Whether the cipher is Authenticated Encryption with Associated Data (AEAD).</dd> <dt><strong>cipher_id</strong> <em>id</em></dt> <dd>The OpenSSL cipher id.</dd> <dt><strong>description</strong> <em>string</em></dt> <dd>A text description of the cipher.</dd> <dt><strong>handshake_digest</strong> <em>boolean</em></dt> <dd>Digest used during handshake.</dd> </dl> </blockquote> <blockquote> <b>Session Info</b> <dl> <dt><strong>alpn</strong> <em>protocol</em></dt> <dd>The protocol selected after Application-Layer Protocol Negotiation (ALPN).</dd> <dt><strong>resumable</strong> <em>boolean</em></dt> <dd>Whether the session can be resumed or not.</dd> <dt><strong>start_time</strong> <em>seconds</em></dt> <dd>Time since session started in seconds since epoch.</dd> <dt><strong>timeout</strong> <em>seconds</em></dt> <dd>Max duration of session in seconds before time-out.</dd> <dt><strong>lifetime</strong> <em>seconds</em></dt> <dd>Session ticket lifetime hint in seconds.</dd> <dt><strong>session_id</strong> <em>binary_string</em></dt> <dd>Unique session id for use in resuming the session.</dd> <dt><strong>session_ticket</strong> <em>binary_string</em></dt> <dd>Unique session ticket for use in resuming the session.</dd> <dt><strong>ticket_app_data</strong> <em>binary_string</em></dt> <dd>Unique session ticket application data.</dd> <dt><strong>master_key</strong> <em>binary_string</em></dt> <dd>Unique session master key.</dd> <dt><strong>session_cache_mode</strong> <em>mode</em></dt> <dd>Server cache mode (client, server, or both).</dd> </dl> </blockquote> <dt><a name="tls::protocols"><strong>tls::protocols</strong></a></dt> <dd>Returns a list of the supported protocols. Valid values are: <b>ssl2</b>, <b>ssl3</b>, <b>tls1</b>, <b>tls1.1</b>, <b>tls1.2</b>, and <b>tls1.3</b>. Exact list depends on OpenSSL version and compile time flags.</dd> <dt><a name="tls::version"><strong>tls::version</strong></a></dt> <dd>Returns the OpenSSL version string.</dd> </dl> <h3><a name="CALLBACK OPTIONS">CALLBACK OPTIONS</a></h3> <p> As indicated above, individual channels can be given their own callbacks to handle intermediate processing by the OpenSSL library, using the <strong>-command</strong>, <strong>-password</strong>, and <strong>-validate_command</strong> options passed to either of <strong>tls::socket</strong> or <strong>tls::import</strong>. If the callback generates an error, the <b>bgerror</b> command will be invoked with the error information. </p> <blockquote> <dl> <dt><strong>-command</strong> <em>callback</em></dt> |
︙ | ︙ | |||
786 787 788 789 790 791 792 | internally. The default behavior when the <strong>-password</strong> option is not specified is for TLS to process the associated library callbacks by attempting to call <strong>tls::password</strong>. The difference between these two behaviors is a consequence of maintaining compatibility with earlier implementations. </p> | < < < < < < < < < < < < < < < > > > > > > > > > > > > > > > | | | | | | 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 | internally. The default behavior when the <strong>-password</strong> option is not specified is for TLS to process the associated library callbacks by attempting to call <strong>tls::password</strong>. The difference between these two behaviors is a consequence of maintaining compatibility with earlier implementations. </p> <p> <em> The use of the reference callbacks <strong>tls::callback</strong>, <strong>tls::password</strong>, and <strong>tls::validate_command</strong> is not recommended. They may be removed from future releases. </em> </p> <h3><a name="DEBUG">DEBUG</a></h3> TLS key logging can be enabled by setting the environment variable <b>SSLKEYLOGFILE</b> to the name of the file to log to. Then whenever TLS key material is generated or received it will be logged to the file. This is useful for logging key data for network logging tools to use to decrypt the data. <p> The <strong>tls::debug</strong> variable provides some additional control over these reference callbacks. Its value is zero by default. Higher values produce more diagnostic output, and will also force the verify method in <strong>tls::callback</strong> to accept the certificate, even when it is invalid. </p> <p> <em> The use of the variable <strong>tls::debug</strong> is not recommended. It may be removed from future releases. </em> </p> <h3><a name="HTTPS EXAMPLE">HTTPS EXAMPLE</a></h3> <p>This example uses a sample server.pem provided with the TLS release, courtesy of the <strong>OpenSSL</strong> project.</p> <pre><code> package require http package require tls http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs] set tok [http::geturl https://www.tcl.tk/] </code></pre> <h3><a name="SPECIAL CONSIDERATIONS">SPECIAL CONSIDERATIONS</a></h3> <p>The capabilities of this package can vary enormously based upon how the linked to OpenSSL library was configured and built. New versions may obsolete older protocol versions, add or remove ciphers, change default values, etc. Use the <strong>tls::protocols</strong> commands to obtain the supported protocol versions.</p> <h3><a name="SEE ALSO">SEE ALSO</a></h3> <p><strong>socket</strong>, <strong>fileevent, </strong><a href="http://www.openssl.org/"><strong>OpenSSL</strong></a></p> <hr> |
︙ | ︙ |