Diff

Differences From Artifact [0f1e2a70be]:

To Artifact [b81dbf8537]:


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
    <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. </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.

    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>








|












>
|







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
    <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>

325
326
327
328
329
330
331
332


333
334
335
336
337
338
339
<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>



    <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>







|
>
>







326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
<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>
389
390
391
392
393
394
395
396


397
398
399
400
401
402
403

    <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>



    <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







|
>
>







392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408

    <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
459
460
461
462
463
464
465
466


467
468
469
470
471
472
473

    <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>



    <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>







|
>
>







464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480

    <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>
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
	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.
<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







|







553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
	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