Tcl Cryptography Documentation
- NAME
- tls - binding to OpenSSL toolkit.
- DESCRIPTION
- SYNOPSIS
- package require Tcl ?8.5-?
- package require tls
-
- tls::cipher name
- tls::ciphers ?protocol? ?verbose? ?supported?
- tls::digests ?name?
- tls::macs
- tls::protocols
- tls::version
-
- tls::cmac -cipher name -key key ?options?
- tls::hmac -digest name -key key ?options?
- tls::md -digest name ?options?
- tls::md4 data
- tls::md5 data
- tls::sha1 data
- tls::sha256 data
- tls::sha512 data
- tls::unstack channelId
- OPTIONS
- COMMANDS
- GLOSSARY
- EXAMPLES
- SPECIAL CONSIDERATIONS
tls - binding to OpenSSL toolkit.
This extension provides a generic interface to the
OpenSSL cryptography functions. The
provided commands can be used to ensure the confidentiality, authenticity,
and integrity of messages and data.
package require Tcl 8.5-
package require tls
tls::cipher name
tls::ciphers ?protocol? ?verbose? ?supported?
tls::digests ?name?
tls::macs
tls::protocols
tls::version
tls::cmac -cipher name -key key ?options?
tls::hmac -digest name -key key ?options?
tls::md -digest name ?options?
tls::md4 data
tls::md5 data
tls::sha1 data
tls::sha256 data
tls::sha512 data
tls::unstack channelId
The following options are used by the cryptography commands.
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.
- -digest name
- Name of hash function (aka message digest) to use.
See tls::digests for the valid values.
- -iterations count
- Number (integer) of iterations on the password to use in deriving the
encryption key. Default is 10000. Some KDF implementations require an
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.
- -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.
- -mac name
- Name of Message Authentication Code (MAC) to use.
See tls::macs for the valid values.
- -password string
- Password to use for some KDF functions.
- -properties list
- List of additional properties to pass to cryptography function.
- -salt string
- 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.
- -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.
- -xof boolean
- Set whether to use XOF. This option is used by KMAC.
Input/Output Options
- -chan channelId
- -channel channelId
- Add the cryptographic transformation on top of channel
channelId. Automatically sets channel to binary mode. Works
like chan push to create a stacked channel. If the command
fileevent is to be used for channel event monitoring, all
channels in the stack should be set to non-blocking mode. If not,
the system may hang while waiting for data. When done, use either the
close command or tls::unstack
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]}
close $ch
puts $md
- -command cmdName
- Create and return cmdName which is used to incrementally add
data to a cryptographic function. To add data to the function, call
"cmdName update data", where
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
- -data string
- Perform the cryptographic function on data and return the
result. Example code:
set md [::tls::digest sha256 "Some example data."]
puts $md
- -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
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.
- -outfile filename
- Specifies the file to send the results to.
- -keyfile filename
- Specifies the file to get the encryption key from.
Format Options
- -base64
- Base64 encode data after encryption or decode before decryption.
- -bin
- -binary
- Output result of function as a binary string.
- -hex
- -hexadecimal
- Output result of function as a hexadecimal string. This is the default
option unless otherwise specified.
The following commands provide access to the OpenSSL cryptography functions.
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.
- 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
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.
- tls::kdfs
- Returns a list of the available Key Derivation Function (KDF)
algorithms.
- tls::macs
- Returns a list of the available Message Authentication Codes (MAC)
for use with the -key option.
- 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
compile time flags.
- tls::version
- Returns the OpenSSL version string.
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]
- 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]
- 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]
- (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
options for usage info.
- tls::md4 data
- Returns the MD4 message-digest for data as a hex string.
- tls::md5 data
- Returns the MD5 message-digest for data as a hex string.
- tls::sha1 data
- Returns the SHA1 secure hash algorithm digest for data as a hex string.
- tls::sha256 data
- Returns the SHA-2 SHA256 secure hash algorithm digest for data as a hex string.
- 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.
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.
TBS
package require http
package require tls
http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs]
set tok [http::geturl https://www.tcl.tk/]
The capabilities of this package can vary enormously based upon how your
OpenSSL library was configured and built. New versions may obsolete older
ciphers, digests, MACs, etc. or change default values. Use the
info commands to obtain the supported values.
Copyright © 2023 Brian O'Hagan.