Index: doc/cryptography.html
==================================================================
--- doc/cryptography.html
+++ doc/cryptography.html
@@ -22,10 +22,11 @@
<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::kdfs</b></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>
@@ -39,11 +40,13 @@
<dd><b>tls::unstack</b> <em>channelId</em></dd>
<dt> </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> </dt>
- <dd><b>tls::derive_key</b> <em>key ?options?</em></dd>
+ <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>
</dl>
</dd>
<dd><a href="#OPTIONS">OPTIONS</a></dd>
<dd><a href="#COMMANDS">COMMANDS</a></dd>
<dd><a href="#GLOSSARY">GLOSSARY</a> </dd>
@@ -71,10 +74,11 @@
<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>
@@ -88,33 +92,50 @@
<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::derive_key"><b>tls::derive_key</b> <i>?options?</i></a><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>
</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 cryptographic cipher to use. Used by encrypt/decrypt command
- and CMAC & 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>
+ <dd>Name of symmetric cipher to use. Used by encrypt/decrypt command
+ and CMAC & 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> for the valid values.</dd>
+ 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. </dd>
</dl>
<dl>
<dt><a name="-iterations"><strong>-iterations</strong> <em>count</em></a></dt>
<dd>Number (integer > 0) of iterations to use in deriving the encryption
@@ -126,12 +147,13 @@
<dt><a name="-iv"><strong>-iv</strong> <em>string</em></a></dt>
<dd>Initialization vector (IV) to use. Required for some ciphers and GMAC.
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>
+ <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
@@ -142,17 +164,18 @@
</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>
+ 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.</dd>
+ 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>
@@ -159,19 +182,29 @@
</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 randomly generated value. This option is
- used by BLAKE2 MAC and some KDF implementations use a non-secret unique
- cryptographic salt.</dd>
+ 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="-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>
+ <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>
@@ -193,14 +226,14 @@
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 dat ""<br>
- while {![eof $ch]} {append dat [read $ch 4096]}<br>
+ set data ""<br>
+ while {![eof $ch]} {append data [read $ch 4096]}<br>
close $ch<br>
- puts $dat
+ 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
@@ -209,15 +242,15 @@
<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>
- set dat ""<br>
- append dat [$cmd update "Some data. "]<br>
- append dat [$cmd update "More data."]<br>
- append dat [$cmd finalize]<br>
- puts $dat
+ 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
@@ -291,40 +324,59 @@
<dl>
<h4><a name="Info">Info Commands</a></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. If block-size is 1,
- then it's a stream cipher, otherwise it's a block cipher.</dd>
+ <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
- <b>tls::protocols</b> command for the supported protocols. If
+ <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 names and values describing message digest <i>name</i>. Properties
- include name, description, size, block_size, type, and flags list.</dd>
+ 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.</dd>
+ 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)
- for use with the <a href="#-key"><b>-key</b></a> option.</dd>
+ <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
@@ -337,45 +389,50 @@
<h4><a name="MD_MAC">Message Digest (MD) and Message Authentication Code (MAC) Commands</a></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>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</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::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>-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>
+ <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><b>-bin</b>|<b>-hex</b><em>?
- [</em><b>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
+ <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>
@@ -401,49 +458,91 @@
<br>
<h4><a name="Cipher">Encryption and Decryption Commands</a></h4>
<dt><a name="tls::encrypt"><strong>tls::encrypt</strong>
- <em>?</em><b>-cipher</b><em>? name</em> <b>-key</b> <em>key ?</em><b>-iv</b> <em>string?
- [</em><b>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
+ <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
- "<b>tls::cipher</b> <em>cipher</em>" command for key and iv
- sizes and when the iv is used (iv_length > 0).</dd>
+ <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 > 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><b>-chan</b> <em>channelId |</em> <b>-command</b> <em>cmdName |</em>
+ <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. Option <b>-iv</b> is only used for some ciphers. See the
- "<b>tls::cipher</b> <em>cipher</em>" command for key and iv
- sizes and when the iv is used (iv_length > 0).</dd>
-</dl>
+ 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 > 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::derive_key"><strong>tls::derive_key</strong>
- <em>[</em><b>-cipher</b> <em>cipher |</em> <b>-size</b> <em>size]</em>
- <b>-digest</b> <em>digest ?</em><b>-iterations</b> <em>count?
- ?</em><b>-password</b> <em>string? ?</em><b>-salt</b> <em>string?</em></a></dt>
+ <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. This is a more secure way to generate
- keys and ivs for use by <a href="#tls::encrypt"><b>tls::encrypt</b></a>.
+ 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>
+ 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>
</dl>
<br>
<h3><a name="GLOSSARY">GLOSSARY</a></h3>