cryptography.html at [c0bbfde5a4]

File doc/cryptography.html artifact c0f7bb9ac4 part of check-in c0bbfde5a4


<!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>&nbsp;</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::kdfs</b></dd>
	    <dd><b>tls::macs</b></dd>
	    <dd><b>tls::protocols</b></dd>
	    <dd><b>tls::version</b></dd>
	    <dt>&nbsp;</dt>
	    <dd><b>tls::cmac</b> <b>-cipher</b> <em>name</em> <b>-key</b> <em>key ?options?</em></dd>
	    <dd><b>tls::digest</b> <b>-digest</b> <em>name ?options?</em></dd>
	    <dd><b>tls::hash</b> <b>-digest</b> <em>name ?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>
	    <dt>&nbsp;</dt>
	    <dd><b>tls::encrypt</b> <b>-cipher</b> <em>name</em> <b>-key</b> <em>key ?options?</em></dd>
	    <dd><b>tls::decrypt</b> <b>-cipher</b> <em>name</em> <b>-key</b> <em>key ?options?</em></dd>
	    <dt>&nbsp;</dt>
	    <dd><b>tls::hkdf -digest</b> <em>digest</em> <b>-key</b> <em>key ?options?</em></dd>
	    <dd><b>tls::pbkdf2 -size</b> <em>length</em> <b>-digest</b> <em>digest ?options?</em></dd>
	    <dd><b>tls::scrypt -password</b> <em>string</em> <b>-salt</b> <em>string ?options?</em></dd>
	    <dt>&nbsp;</dt>
	    <dd><b>tls::random</b> <em>?</em><b>-private</b><em>? length</em></dd>
	    <dt>&nbsp;</dt>
	    <dd><b>tls::provider</b> <em>name</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::kdfs"><b>tls::kdfs</b></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::digest"><b>tls::digest</b> <b>-digest</b> <i>name ?options?</i></a><br>
<a href="#tls::hash"><b>tls::hash</b> <b>-digest</b> <i>name ?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>
<br>
<a href="#tls::encrypt"><b>tls::encrypt</b> <b>-cipher</b> <i>name</i> <b>-key</b> <i>key ?options?</i></a><br>
<a href="#tls::decrypt"><b>tls::decrypt</b> <b>-cipher</b> <i>name</i> <b>-key</b> <i>key ?options?</i></a><br>
<br>
<a href="#tls::hkdf"><b>tls::hkdf -digest</b> <i>digest</i> <b>-key</b> <i>key ?options?</i></a><br>
<a href="#tls::pbkdf2"><b>tls::pbkdf2 -size</b> <i>length</i> <b>-digest</b> <i>digest ?options?</i></a><br>
<a href="#tls::scrypt"><b>tls::scrypt -password</b> <i>string</i> <b>-salt</b> <i>string ?options?</i></a><br>
<br>
<a href="#tls::random"><b>tls::random</b> <i>?</i><b>-private</b><i>? length</i></a><br>
<br>
<a href="#tls::provider"><b>tls::provider</b> <i>name</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="-aad_data"><strong>-aad_data</strong> <em>string</em></a></dt>
    <dd>Additional Authenticated Data (AAD).</dd>
</dl>

<dl>
    <dt><a name="-cipher"><strong>-cipher</strong> <em>name</em></a></dt>
    <dd>Name of symmetric cipher to use. Used by encrypt/decrypt command
    and CMAC &amp; GMAC hash algorithms. For CMAC, it must be one of
    <b>AES-128-CBC</b>, <b>AES-192-CBC</b>, <b>AES-256-CBC</b>, or
    <b>DES-EDE3-CBC</b>. For GMAC it should be a GCM mode cipher (e.g.
    AES-128-GCM). See <a href="#tls::ciphers"><b>tls::ciphers</b></a>
    command for the valid values. Only CCM and GCM modes (also  known as Authenticated
    Encryption with Associated Data (AEAD) modes) provide both confidentially
    and integrity protection.</dd>
</dl>

<dl>
    <dt><a name="-digest"><strong>-digest</strong> <em>name</em></a></dt>
    <dt><a name="-hash"><strong>-hash</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> command for the valid values.</dd>
</dl>

<dl>
    <dt><a name="-info"><strong>-info</strong> <em>string</em></a></dt>
    <dd>Optional context and application specific information. Can be a binary
    or text string. Max length is 1024 bytes for OpenSSL 1.1 and 2048 bytes for 3.0.</dd>
</dl>

<dl>
    <dt><a name="-iterations"><strong>-iterations</strong> <em>count</em></a></dt>
    <dd>Number (integer &gt; 0) of iterations to use in deriving the encryption
    key. Default is 2048. Some <a href="#KDF"><b>KDF</b></a> implementations
    require an iteration count.</dd>
</dl>

<dl>
    <dt><a name="-iv"><strong>-iv</strong> <em>string</em></a></dt>
    <dd>Initialization vector (IV) to use. Required for some ciphers and GMAC.
    Other MACs use a fixed IV.
    Cipher modes CBC, CFB, and OFB all need an IV, while ECB and CTR modes do 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. See the
   <a href="#tls::cipher"><b>tls::cipher</b></a> for iv_length and when
   required (length > 0). Max is 16 bytes. If not set, it will default to \x00
   fill data.</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 ciphers, HMAC,
    some CMAC, and some KDF implementations. If the length of the key is &lt;
    <b>key_length</b> it will be padded. Max is 64 bytes. If &gt; key_length, it will be rejected.
    See the <a href="#tls::cipher"><b>tls::cipher</b></a> for key_length.</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> command 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. If not specified, the default
    value is used. Can be a binary or text string. For KDF commands, this is
    the same as the <b>-key</b> option.</dd>
</dl>

<dl>
    <dt><a name="-properties"><strong>-properties</strong> <em>list</em></a></dt>
    <dd>List of additional properties to pass to cryptographic 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. Can be a binary or
    text string. Default is to use a string of \0's. It is best to use a
    uniquely and 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="-length"><strong>-length</strong> <em>integer</em></a></dt>
    <dt><a name="-size"><strong>-size</strong> <em>integer</em></a></dt>
    <dd>Set the output hash or KDF length in bytes. Used by KDFs, KMAC128, and
    KMAC256 to specify an output length in bytes. The default size
    for KMAC128 is 32 bytes and KMAC256 is 64 bytes.</dd>
</dl>

<dl>
    <dt><a name="-auth_tag"><strong>-tag</strong> <em>string</em></a></dt>
    <dt><a name="-tag"><strong>-tag</strong> <em>string</em></a></dt>
    <dd>Authenticated Encryption and Authenticated Data (AEAD) tag.
    Can be a binary or text string. Max is 16 bytes. A minimum of 12
    bytes is recommended.</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>
		set data ""<br>
		while {![eof $ch]} {append data [read $ch 4096]}<br>
		close $ch<br>
		puts $data
    </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
	&quot;<em>cmdName</em> <b>update</b> <em>data</em>&quot;, where
	<em>data</em> is the data to add. When done, call
	&quot;<em>cmdName</em> <b>finalize</b>&quot; 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>
		set data ""<br>
		append data [$cmd update "Some data. "]<br>
		append data [$cmd update "More data."]<br>
		append data [$cmd finalize]<br>
		puts $data
    </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 file 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. This option uses the
    TCL file APIs, so VFS files are supported. Example code:</dd></dl>
    <blockquote><code>
		::tls::encrypt -cipher aes-128-cbc -key "Test key"
		-infile unencrypted.txt -outfile encrypted.dat
    </code></blockquote>

<dl>
    <dt><a name="-outfile"><strong>-outfile</strong> <em>filename</em></a></dt>
    <dd>Specifies the file to output the encryption results to. This option
    uses the TCL file APIs, so VFS files are supported. Example code:</dd></dl>
    <blockquote><code>
		::tls::decrypt -cipher aes-128-cbc -key "Test key"
		-infile encrypted.dat -outfile unencrypted.txt
    </code></blockquote>

<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><a name="Info">Info Commands</a></h4>
These commands provide information about the available ciphers, digests, etc. and their properties.
<br>
<br>
    <dt><a name="tls::cipher"><strong>tls::cipher</strong> <em>name</em></a></dt>
    <dd>Returns a list of property name and value pairs describing cipher
	<i>name</i>. Properties are:</dd>
    <blockquote><table>
	<tr><td><b>nid</b></td><td>Internal id of cipher. This is the same as <i>name</i>.<td></tr>
	<tr><td><b>name</b></td><td>Name or alias of the cipher.<td></tr>
	<tr><td><b>description</b></td><td>Description of the cipher. OpenSSL 3.0+ only.<td></tr>
	<tr><td><b>block_size</b></td><td>Block size of the cipher. Stream ciphers are set to 1.<td></tr>
	<tr><td><b>key_length</b></td><td>key length of a cipher in bytes.<td></tr>
	<tr><td><b>iv_length</b></td><td>IV length of a cipher in bytes or 0 if not used.<td></tr>
	<tr><td><b>type</b></td><td>Base type of this cipher or undefined if none.<td></tr>
	<tr><td><b>provider</b></td><td>Provider of the cipher. OpenSSL 3.0+ only.<td></tr>
	<tr><td><b>mode</b></td><td>Block cipher mode or <b>stream</b> for a stream cipher.<td></tr>
	<tr><td><b>flags</b></td><td>Flags associated with the cipher. Includes: Variable Length, AEAD Cipher, Non FIPS Allow, etc.<td></tr>
    </table></blockquote>

    <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
	 <a href="#tls::protocols"><b>tls::protocols</b></a> 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 name and value
	pairs describing message digest <i>name</i>. Properties are:</dd>
    <blockquote><table>
	<tr><td><b>name</b></td><td>Name or alias of the digest.<td></tr>
	<tr><td><b>description</b></td><td>Description of the digest. OpenSSL 3.0+ only.<td></tr>
	<tr><td><b>size</b></td><td>Size of the digest in bits.<td></tr>
	<tr><td><b>block_size</b></td><td>Block size of digest in bytes.<td></tr>
	<tr><td><b>provider</b></td><td>Provider of the digest. OpenSSL 3.0+ only.<td></tr>
	<tr><td><b>type</b></td><td>Base type of this digest or undefined if none.<td></tr>
	<tr><td><b>pkey_type</b></td><td>Pkey associated with digest.<td></tr>
	<tr><td><b>flags</b></td><td>Flags associated with the digest. Includes: One-shot, XOF, etc.<td></tr>
    </table></blockquote>

    <dt><a name="tls::kdfs"><strong>tls::kdfs</strong></a></dt>
    <dd>Returns a list of the available Key Derivation Function (KDF)
	algorithms. Each item in the list corresponds to a command with the same name.</dd>

    <dt><a name="tls::macs"><strong>tls::macs</strong></a></dt>
    <dd>Returns a list of the available Message Authentication Codes (MAC).
	Each item in the list corresponds to a command with the same name.</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><a name="MD_MAC">Message Digest (MD) and Message Authentication Code (MAC) Commands</a></h4>
These commands calculate a message digest or message authentication code for data.
<br>
<br>
    <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>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
	<b>-file</b> <em>filename | ?</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::digest"><strong>tls::digest</strong>
	<em>option value ...</em></a></dt>
    <dd>Alias for <b>tls::md</b>.</dd>

    <dt><a name="tls::hash"><strong>tls::hash</strong>
	<em>option value ...</em></a></dt>
    <dd>Alias for <b>tls::md</b>.</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>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
	<b>-file</b> <em>filename | ?</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>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
	<b>-file</b> <em>filename | ?</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>
	<em>?</em><b>-bin</b>|<b>-hex</b>
	<em>?[</em><b>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
	<b>-file</b> <em>filename | ?</em><b>-data</b><em>? data]</em></a></dt>
    <dd>Calculate the message digest (MD) using hash function <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>

<br>

<h4><a name="Cipher">Encryption and Decryption Commands</a></h4>
These commands encrypt plaintext into ciphertext or vice versa.
<br>
<br>
    <dt><a name="tls::encrypt"><strong>tls::encrypt</strong>
	<em>?</em><b>-cipher</b><em>? name</em>
	<b>-digest</b> <em>name</em>
	<b>-key</b> <em>key ?</em>
	<b>-iv</b> <em>string?</em>
	<em>[</em><b>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
	<b>-infile</b> <em>filename</em> <b>-outfile</b> <em>filename |</em>
	<b>-data</b><em> data]</em></a></dt>
    <dd>Encrypt the data using cipher <em>cipher</em> and output the result per
	the I/O options. Ciphers are used to create the cipher text from the
	input data. See <a href="#OPTIONS"><b>options</b></a> for usage
	info. Option <b>-iv</b> is only used for some ciphers. See the
	<a href="#tls::cipher"><b>tls::cipher</b></a> command for key and iv
	sizes and for when the <b>-iv</b> option is used (iv_length &gt; 0).</dd>

    <dt><a name="tls::decrypt"><strong>tls::decrypt</strong>
	<em>?</em><b>-cipher</b><em>? name</em>
	<b>-key</b> <em>key ?</em>
	<b>-iv</b> <em>string?</em>
	<em>[</em><b>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
	<b>-infile</b> <em>filename</em> <b>-outfile</b> <em>filename |</em>
	<b>-data</b><em> data]</em></a></dt>
    <dd>Decrypt the data using cipher <em>cipher</em> and output the result per
	the I/O options. This command is the opposite of the <b>tls::encrypt</b>
	command. See <a href="#OPTIONS"><b>options</b></a> for usage info.
	The <b>-iv</b> option is only used for some ciphers. See the
	<a href="#tls::cipher"><b>tls::cipher</b></a> command for key and iv
	sizes and for when the <b>-iv</b> option is used (iv_length &gt; 0).</dd>

<br>

<h4><a name="KDF">Key Derivation Function (KDF) Commands</a></h4>
These commands are a more secure way to generate keys and ivs for use by the
<a href="#tls::encrypt"><b>tls::encrypt</b></a> command then regular strings and random values.
<br>
<br>
    <dt><a name="tls::hkdf"><strong>tls::hkdf</strong>
	<b>-digest</b> <em>digest</em>
	<b>-key</b> <em>string</em>
	<em>?</em><b>-info</b> <em>string?</em>
	<em>?</em><b>-salt</b> <em>string?</em>
	<em>?</em><b>-size</b> <em>derived_length?</em></a></dt>
    <dd>Derive a key of size <i>size</i> using the HMAC-based Extract-and-Expand
	Key Derivation Function (HKDF).
	See <a href="#OPTIONS"><b>options</b></a> for usage info. </dd>

    <dt><a name="tls::pbkdf2"><strong>tls::pbkdf2</strong>
	<em>[</em><b>-cipher</b> <em>cipher |</em>
	<b>-size</b> <em>derived_length]</em>
	<b>-digest</b> <em>digest</em>
	<em>?</em><b>-iterations</b> <em>count?</em>
	<em>?</em><b>-password</b> <em>string?</em>
	<em>?</em><b>-salt</b> <em>string?</em></a></dt>
    <dd>Derive a key and initialization vector (iv) from a password and salt
	value using PKCS5_PBKDF2_HMAC. 
	See <a href="#OPTIONS"><b>options</b></a> for usage info. If <b>-cipher</b>
	is specified, then the derived key and iv sized for that cipher are
	returned as a key-value list. If not or if <b>-size</b> is specified,
	then the derived key (DK) of <em>size</em> bytes is returned.</dd>

    <dt><a name="tls::scrypt"><strong>tls::scrypt</strong>
	<b>-password</b> <em>string</em>
	<b>-salt</b> <em>string</em>
	<em>?</em><b>-N</b> <em>costParameter?</em>
	<em>?</em><b>-r</b> <em>blockSize?</em>
	<em>?</em><b>-p</b> <em>parallelization?</em>
	<em>?</em><b>-size</b> <em>derived_length?</em></a></dt>
    <dd>Derive a key of size <i>size</i> using the scrypt password based key derivation function.
	See <a href="#OPTIONS"><b>options</b></a> for usage info. 
	See RFC 7914 for more details. Can consume a large amount of memory.
	RAM used is roughly (128 * N * r * p) bytes. Memory is limited to
	1025 MiB. The custom options are:</dd>
    <blockquote><table>
	<tr><td><b>-N</b></td><td>The CPU/Memory cost parameter
	must be larger than 1, a power of 2, and less than
	2^(128 * r / 8). Default is 1048576.<td></tr>
	<tr><td><b>-r</b></td><td>The blockSize parameter specifies the
	block size. Must be greater than 0. Default is 8.<td></tr>
	<tr><td><b>-p</b></td><td>The parallelization parameter
	must be a positive integer less than or equal
	to ((2^32-1) * 32) / (128 * r). Default is 1.<td></tr>
    </table></blockquote>

<br>

<h4><a name="RAND">Random Bytes Commands</a></h4>
These commands provide randomly generated byte strings for use when random data is needed.
<br>
<br>
    <dt><a name="tls::random"><strong>tls::random</strong>
	<em>?</em><b>-private</b><em>? length</em></a></dt>
    <dd>Generate <i>length</i> random bytes using a cryptographically secure
	pseudo random generator (CSPRNG). OpenSSL uses a security level of 256
	bits. Will return an error if a trusted entropy source such as the OS
	isn't available. Use <b>-private</b> option if the values are intended
	to remain private in case the public PRNG is compromised.</dd>

<br>

<h4><a name="PROVIDER">Load Provider</a></h4>
These commands provide access to the OpenSSL providers.
<br>
<br>
    <dt><a name="tls::provider"><strong>tls::provider</strong>
	<em>name</em></a></dt>
    <dd>Load <i>name</i> default provider. Valid provider names are:
    <b>default</b>, <b>base</b>, <b>fips</b>, and <b>legacy</b>. Use
    <b>legacy</b> to load the legacy provider ciphers, digests, etc.</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 &copy; 2023 Brian O'Hagan.
</pre>
</body>
</html>