Index: doc/cryptography.html ================================================================== --- doc/cryptography.html +++ doc/cryptography.html @@ -22,10 +22,11 @@
package require tls
 
tls::cipher name
tls::ciphers ?protocol? ?verbose? ?supported?
tls::digests ?name?
+
tls::kdfs
tls::macs
tls::protocols
tls::version
 
tls::cmac -cipher name -key key ?options?
@@ -39,11 +40,13 @@
tls::unstack channelId
 
tls::encrypt -cipher name -key key ?options?
tls::decrypt -cipher name -key key ?options?
 
-
tls::derive_key key ?options?
+
tls::hkdf -digest digest -key key ?options?
+
tls::pbkdf2 -size length -digest digest ?options?
+
tls::scrypt -password string -salt string ?options?
OPTIONS
COMMANDS
GLOSSARY
@@ -71,10 +74,11 @@ package require tls

tls::cipher name
tls::ciphers ?protocol? ?verbose? ?supported?
tls::digests ?name?
+tls::kdfs
tls::macs
tls::protocols
tls::version

tls::cmac -cipher name -key key ?options?
@@ -88,33 +92,50 @@ tls::unstack channelId

tls::encrypt -cipher name -key key ?options?
tls::decrypt -cipher name -key key ?options?

-tls::derive_key ?options?
+tls::hkdf -digest digest -key key ?options?
+tls::pbkdf2 -size length -digest digest ?options?
+tls::scrypt -password string -salt string ?options?


OPTIONS

The following options are used by the cryptography commands.


Cryptographic Options

+
+
-aad_data string
+
Additional Authenticated Data (AAD).
+
+
-cipher name
-
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 tls::ciphers - for the valid values.
+
Name of symmetric 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 tls::ciphers + 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.
-digest name
+
-hash name
Name of hash function (aka message digest) to use. - See tls::digests for the valid values.
+ See tls::digests command for the valid values. +
+ +
+
-info string
+
Optional context and application specific information. Can be a binary + or text string.
-iterations count
Number (integer > 0) of iterations to use in deriving the encryption @@ -126,12 +147,13 @@
-iv string
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 - tls::cipher for iv_length and - when required (length > 0). Max is 16 bytes. If not set, it will default to \x00 fill data.
+ tls::cipher for iv_length and when + required (length > 0). Max is 16 bytes. If not set, it will default to \x00 + fill data.
-key string
Encryption key to use for cryptography function. Can be a binary or @@ -142,17 +164,18 @@
-mac name
Name of Message Authentication Code (MAC) to use. - See tls::macs for the valid values.
+ See tls::macs command for the valid values.
-password string
Password to use for some KDF functions. If not specified, the default - value is used. Can be a binary or text string.
+ value is used. Can be a binary or text string. For KDF commands, this is + the same as the -key option.
-properties list
List of additional properties to pass to cryptographic function.
@@ -159,19 +182,29 @@
-salt string
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.
+ 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. +
+ +
+
-length integer
+
-size integer
+
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.
-
-size number
-
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.
+
-tag string
+
-tag string
+
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.
-xof boolean
Set whether to use XOF. This option is used by KMAC.
@@ -193,14 +226,14 @@ to remove the transform from the channel. Additional transforms cannot be added to channel. Example code:
set ch [open test_file.txt rb]
::tls::digest -digest sha256 -chan $ch
- set dat ""
- while {![eof $ch]} {append dat [read $ch 4096]}
+ set data ""
+ while {![eof $ch]} {append data [read $ch 4096]}
close $ch
- puts $dat + puts $data
-command cmdName
Create and return cmdName which is used to incrementally add @@ -209,15 +242,15 @@ data is the data to add. When done, call "cmdName finalize" to return the resulting value and delete cmdName. Example code:
set cmd [::tls::digest -digest sha256 -command ::tls::temp]
- set dat ""
- append dat [$cmd update "Some data. "]
- append dat [$cmd update "More data."]
- append dat [$cmd finalize]
- puts $dat + set data ""
+ append data [$cmd update "Some data. "]
+ append data [$cmd update "More data."]
+ append data [$cmd finalize]
+ puts $data
-data string
Perform the cryptographic function on data and return the @@ -291,40 +324,59 @@

Info Commands

tls::cipher name
-
Return a list of property names and values describing cipher - name. 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.
+
Returns a list of property name and value pairs describing cipher + name. Properties are:
+
+ + + + + + + + + + +
nidInternal id of cipher. This is the same as name.
nameName or alias of the cipher.
descriptionDescription of the cipher. OpenSSL 3.0+ only.
block_sizeBlock size of the cipher. Stream ciphers are set to 1.
key_lengthkey length of a cipher in bytes.
iv_lengthIV length of a cipher in bytes or 0 if not used.
typeBase type of this cipher or undefined if none.
providerProvider of the cipher. OpenSSL 3.0+ only.
modeBlock cipher mode or stream for a stream cipher.
flagsFlags associated with the cipher. Includes: Variable Length, AEAD Cipher, Non FIPS Allow, etc.
tls::ciphers ?protocol? ?verbose? ?supported?
Without any args, returns a list of all symmetric ciphers for use with the -cipher option. With protocol, only the ciphers supported for that protocol are returned. See - tls::protocols command for the supported protocols. If + tls::protocols command for the supported protocols. If verbose is specified as true then a verbose, human readable list is returned with additional information on the cipher. If supported is specified as true, then only the ciphers supported for protocol will be listed.
tls::digests ?name?
Without name, returns a list of the supported message digests (aka hash algorithms) for use with the -digest - option. With name, returns a list of - property names and values describing message digest name. Properties - include name, description, size, block_size, type, and flags list.
+ option. With name, returns a list of property name and value + pairs describing message digest name. Properties are:
+
+ + + + + + + + +
nameName or alias of the digest.
descriptionDescription of the digest. OpenSSL 3.0+ only.
sizeSize of the digest in bits.
block_sizeBlock size of digest in bytes.
providerProvider of the digest. OpenSSL 3.0+ only.
typeBase type of this digest or undefined if none.
pkey_typePkey associated with digest.
flagsFlags associated with the digest. Includes: One-shot, XOF, etc.
tls::kdfs
Returns a list of the available Key Derivation Function (KDF) - algorithms.
+ algorithms. Each item in the list corresponds to a command with the same name.
tls::macs
-
Returns a list of the available Message Authentication Codes (MAC) - for use with the -key option.
+
Returns a list of the available Message Authentication Codes (MAC). + Each item in the list corresponds to a command with the same name.
tls::protocols
Returns a list of supported protocols. Valid values are: ssl2, ssl3, tls1, tls1.1, tls1.2, and tls1.3. Exact list depends on OpenSSL version and @@ -337,45 +389,50 @@

Message Digest (MD) and Message Authentication Code (MAC) Commands

tls::cmac ?-cipher? name - -key key ?-bin|-hex? - [-chan channelId | -command cmdName | + -key key ? + -bin|-hex + ?[-chan channelId | -command cmdName | -file filename | ?-data? data]
Calculate the Cipher-based Message Authentication Code (CMAC) where key 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 options for usage info. Option -key is only used for some ciphers.
tls::hmac ?-digest? name - -key key ?-bin|-hex? - [-chan channelId | -command cmdName | + -key key ? + -bin|-hex + ?[-chan channelId | -command cmdName | -file filename | ?-data? data]
Calculate the Hash-based Message Authentication Code (HMAC) where key 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 options for usage info.
tls::mac - ?-mac? name -cipher name - -digest name -key key ? - -bin|-hex? - [-chan channelId | -command cmdName | + ?-mac? name + -cipher name + -digest name + -key key ? + -bin|-hex + ?[-chan channelId | -command cmdName | -file filename | ?-data? data]
(OpenSSL 3.0+) Calculate the Message Authentication Code (MAC) where key 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 options for usage info.
tls::md - ?-digest? name ?-bin|-hex? - [-chan channelId | -command cmdName | + ?-digest? name + ?-bin|-hex + ?[-chan channelId | -command cmdName | -file filename | ?-data? data]
Calculate the message digest (MD) using hash function name and output the result per the I/O options in the specified format. MDs are used to ensure the integrity of data. See options for usage info.
@@ -401,49 +458,91 @@

Encryption and Decryption Commands

tls::encrypt - ?-cipher? name -key key ?-iv string? - [-chan channelId | -command cmdName | + ?-cipher? name + -digest name + -key key ? + -iv string? + [-chan channelId | -command cmdName | -infile filename -outfile filename | -data data]
Encrypt the data using cipher cipher and output the result per the I/O options. Ciphers are used to create the cipher text from the input data. See options for usage info. Option -iv is only used for some ciphers. See the - "tls::cipher cipher" command for key and iv - sizes and when the iv is used (iv_length > 0).
+ tls::cipher command for key and iv + sizes and for when the -iv option is used (iv_length > 0).
tls::decrypt - ?-cipher? name -key key ?-iv string? - [-chan channelId | -command cmdName | + ?-cipher? name + -key key ? + -iv string? + [-chan channelId | -command cmdName | -infile filename -outfile filename | -data data]
Decrypt the data using cipher cipher and output the result per the I/O options. This command is the opposite of the tls::encrypt - command. See options for usage - info. Option -iv is only used for some ciphers. See the - "tls::cipher cipher" command for key and iv - sizes and when the iv is used (iv_length > 0).
-
+ command. See options for usage info. + The -iv option is only used for some ciphers. See the + tls::cipher command for key and iv + sizes and for when the -iv option is used (iv_length > 0).

Key Derivation Function (KDF) Commands

+These commands are a more secure way to generate keys and ivs for use by the +tls::encrypt command then regular strings and random values. +
+
+
tls::hkdf + -digest digest + -key string + ?-info string? + ?-salt string? + ?-size derived_length?
+
Derive a key of size size using the HMAC-based Extract-and-Expand + Key Derivation Function (HKDF). + See options for usage info.
-
tls::derive_key - [-cipher cipher | -size size] - -digest digest ?-iterations count? - ?-password string? ?-salt string?
+
tls::pbkdf2 + [-cipher cipher | + -size derived_length] + -digest digest + ?-iterations count? + ?-password string? + ?-salt string?
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 tls::encrypt. + value using PKCS5_PBKDF2_HMAC. See options for usage info. If -cipher is specified, then the derived key and iv sized for that cipher are returned as a key-value list. If not or if -size is specified, - then the derived key (dk) of size bytes is returned.
+ then the derived key (DK) of size bytes is returned. + +
tls::scrypt + -password string + -salt string + ?-N costParameter? + ?-r blockSize? + ?-p parallelization? + ?-size derived_length?
+
Derive a key of size size using the scrypt password based key derivation function. + See options 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:
+
+ + + +
-NThe CPU/Memory cost parameter + must be larger than 1, a power of 2, and less than + 2^(128 * r / 8). Default is 1048576.
-rThe blockSize parameter specifies the + block size. Must be greater than 0. Default is 8.
-pThe parallelization parameter + must be a positive integer less than or equal + to ((2^32-1) * 32) / (128 * r). Default is 1.

GLOSSARY