TclTLS
Check-in [17448b5ea7]
Login
HomeTimelineDownloadBrowse SourceBranchesTagsTicketsWiki
Overview
Comment:Updated documentation to add KDF commands, list KDFs command, and list cipher/digest info attributes.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | crypto
Files: files | file ages | folders
SHA3-256: 17448b5ea7d4d4f9a609b81ff7de41829ac6ba89f3621c8dc80c7495c55ba696
User & Date: bohagan on 2023-12-25 03:58:24
Other Links: branch diff | manifest | tags
Context
2023-12-28
03:00
Added random bytes command to generate random bytes using a cryptographically secure pseudo random generator (CSPRNG). check-in: baa34f4208 user: bohagan tags: crypto
2023-12-25
03:58
Updated documentation to add KDF commands, list KDFs command, and list cipher/digest info attributes. check-in: 17448b5ea7 user: bohagan tags: crypto
02:04
Added KDF test cases check-in: 4cc32676a2 user: bohagan tags: crypto
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Modified doc/cryptography.html from [b22c8f2c44] to [30f9acbd70].

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

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








>

















|
>
>








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

    <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::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>
	</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>
︙︙
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


<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>
<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>
<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 encrypt/decrypt command
    and CMAC &amp; 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 &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>

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

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









>

















|
>
>










>
>
>
>
>

|
|
>
|
|
|
>
>




>

|
>
>
>
>
>
>















|
|
>














|





|
>










>
|
|
>
|
>
>
>
>
>
>



|
|
>
>
|








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


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

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

	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 dat ""<br>
		while {![eof $ch]} {append dat [read $ch 4096]}<br>
		close $ch<br>
		puts $dat
    </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 dat ""<br>
		append dat [$cmd update "Some data. "]<br>
		append dat [$cmd update "More data."]<br>
		append dat [$cmd finalize]<br>
		puts $dat
    </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>








|
|

|












|
|
|
|
|








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

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

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



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








|
|
>
>
>
>
>
|
>
>
>
|
>
>






|








|
|
>
>
|
>
>
>
>
>
>
>



|


|
|
















|
>
|









|
>
|








|
>
|
>
|
|








|
>
|








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

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

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

    <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>-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
	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
	&quot;<b>tls::cipher</b> <em>cipher</em>&quot; command for key and iv
	sizes and when the iv 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><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
	&quot;<b>tls::cipher</b> <em>cipher</em>&quot; command for key and iv
	sizes and when the iv is used (iv_length &gt; 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>








|
>
>
>
|






|
|


|
>
>
|




|
|
|
|
<




>
>
>
>
>
>
>
>
>
>
>
>
>

|
|
>
|
>
>
|

|
<



|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>








456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489

490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516

517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550

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

Powered by Fossil · RSS