| ︙ | | |
36
37
38
39
40
41
42
43
44
45
46
47
48
49
|
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
|
+
+
|
<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> </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>
</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>
|
| ︙ | | |
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
+
+
|
<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::derive_key"><b>tls::derive_key</b> <i>?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>
|
| ︙ | | |
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
|
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
|
-
-
-
+
+
+
-
+
-
+
-
+
-
+
+
-
+
-
-
-
+
+
+
+
|
<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>
<dd>Number (integer > 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, OFB and CTR all need an IV while ECB mode does not.
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). If not set, it will default to \x00 fill data.</dd>
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 <
<b>key_length</b> it will be padded. If > key_length, it will be rejected.
<b>key_length</b> it will be padded. Max is 64 bytes. If > 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> 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>
<dd>Password to use for some KDF functions. If not specified, the default
value is used. Can be a binary or text string.</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>
<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. 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>
<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>
</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>
|
| ︙ | | |
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
-
+
|
<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>
<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>
|
| ︙ | | |
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
|
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
-
+
|
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>
<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
|
| ︙ | | |
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
|
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
|
-
+
|
<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>Encryption and Decryption Commands</h4>
<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>
<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
|
| ︙ | | |
417
418
419
420
421
422
423
424
425
426
427
428
429
430
|
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
452
453
|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|
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>
<br>
<h4><a name="KDF">Key Derivation Function (KDF) Commands</a></h4>
<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>
<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>.
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>
</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>
|
| ︙ | | |