Index: doc/cryptography.html
==================================================================
--- doc/cryptography.html
+++ doc/cryptography.html
@@ -35,10 +35,13 @@
tls::md5 data
tls::sha1 data
tls::sha256 data
tls::sha512 data
tls::unstack channelId
+
+ tls::encrypt -cipher name -key key ?options?
+ tls::decrypt -cipher name -key key ?options?
OPTIONS
COMMANDS
GLOSSARY
@@ -79,10 +82,13 @@
tls::md5 data
tls::sha1 data
tls::sha256 data
tls::sha512 data
tls::unstack channelId
+
+tls::encrypt -cipher name -key key ?options?
+tls::decrypt -cipher name -key key ?options?
@@ -90,14 +96,15 @@
Cryptographic Options
- -cipher name
- - Name of cryptographic cipher to use. Used by the CMAC and 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 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.
- -digest name
- Name of hash function (aka message digest) to use.
@@ -111,19 +118,25 @@
iteration count.
- -iv string
- - Initialization vector (IV). Required for GMAC. Cipher modes CBC, CFB, OFB and CTR all need an initialization vector (IV) while ECB mode does 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.
+ - 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.
+ 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 command for iv size and
+ when required.
- -key string
- Encryption key to use for cryptography function. Can be a binary or
- text string. Longer keys provide
- better protection. Used by HMAC, some CMAC, and some KDF implementations.
- Some functions require key length must conform to key_length size.
+ text string. Longer keys provide better protection. Used by ciphers, HMAC,
+ some CMAC, and some KDF implementations. Key lengths less than key_length
+ size may be padded or rejected. See the
+ tls::cipher command for key size.
- -mac name
- Name of Message Authentication Code (MAC) to use.
@@ -174,13 +187,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
- while {![eof $ch]} {set md [read $ch 4096]}
+ set dat ""
+ while {![eof $ch]} {append dat [read $ch 4096]}
close $ch
- puts $md
+ puts $dat
- -command cmdName
- Create and return cmdName which is used to incrementally add
@@ -189,14 +203,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]
- $cmd update "Some data. "
- $cmd update "More data."
- set md [$cmd finalize]
- puts $md
+ set dat ""
+ append dat [$cmd update "Some data. "]
+ append dat [$cmd update "More data."]
+ append dat [$cmd finalize]
+ puts $dat
- -data string
- Perform the cryptographic function on data and return the
@@ -209,24 +224,34 @@
- -file filename
- -filename filename
- Perform the cryptographic function on file filename and return
the result. This operation will open file, read the file data, close the
- file, and return the result using the TCL APIs, so VFS files are
+ file, and return the result using the TCL file APIs, so VFS files are
supported. Example code:
set md [::tls::digest -digest sha256 -file test_file.txt]
puts $md
- -infile filename
- - Specifies the file to use as data input source.
+ - Specifies the file to use as data input source. This option uses the
+ TCL file APIs, so VFS files are supported. Example code:
+
+ ::tls::encrypt -cipher aes-128-cbc -key "Test key"
+ -infile unencrypted.txt -outfile encrypted.dat
+
- -outfile filename
- - Specifies the file to send the results to.
+ Specifies the file to output the encryption results to. This option
+ uses the TCL file APIs, so VFS files are supported. Example code:
+
+ ::tls::decrypt -cipher aes-128-cbc -key "Test key"
+ -infile encrypted.dat -outfile unencrypted.txt
+
- -keyfile filename
- Specifies the file to get the encryption key from.
@@ -306,48 +331,48 @@
Message Digest (MD) and Message Authentication Code (MAC) Commands
tls::cmac
?-cipher? name
-key key ?-bin|-hex?
- [-file filename | -command cmdName |
- -chan channelId | ?-data? data]
+ [-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?
- [-file filename | -command cmdName |
- -chan channelId | ?-data? data]
+ [-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? [-file
- filename | -command cmdName |
- -chan channelId | ?-data? data]
+ -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?
- [-file filename | -command cmdName |
- -chan channelId | ?-data? data]
- Calculate the message digest (MD) using hash function (aka message
- digest) name and output the result per the I/O options in the
- specified format. MDs are used to ensure the integrity of data. See
+ [-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.
tls::md4 data
Returns the MD4 message-digest for data as a hex string.
@@ -363,10 +388,38 @@
tls::sha512 data
Returns the SHA-2 SHA512 secure hash algorithm digest for data as a hex string.
tls::unstack channelId
Removes the top level cryptographic transform from channel channelId.
+
+
+
+Encryption and Decryption Commands
+
+ tls::encrypt
+ -cipher 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::decrypt
+ -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).