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::kdfs
- tls::macs
- tls::protocols
- tls::version
-
- tls::cmac -cipher name -key key ?options?
- tls::digest -digest name ?options?
- tls::hash -digest name ?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
-
- tls::encrypt -cipher name -key key ?options?
- tls::decrypt -cipher name -key key ?options?
-
- tls::hkdf -digest digest -key key ?options?
- tls::pbkdf2 -size length -digest digest ?options?
- tls::scrypt -password string -salt string ?options?
-
- tls::random ?-private? length
-
- tls::provider name
- 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::kdfs
tls::macs
tls::protocols
tls::version
tls::cmac -cipher name -key key ?options?
tls::digest -digest name ?options?
tls::hash -digest name ?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
tls::encrypt -cipher name -key key ?options?
tls::decrypt -cipher name -key key ?options?
tls::hkdf -digest digest -key key ?options?
tls::pbkdf2 -size length -digest digest ?options?
tls::scrypt -password string -salt string ?options?
tls::random ?-private? length
tls::provider name
The following options are used by the cryptography commands.
Cryptographic Options
- -aad_data string
- Additional Authenticated Data (AAD).
- -cipher name
- 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 command for the valid values.
- -info string
- Optional context and application specific information. Can be a binary
or text string. Max length is 1024 bytes for OpenSSL 1.1 and 2048 bytes for 3.0.
- -iterations count
- Number (integer > 0) of iterations to use in deriving the encryption
key. Default is 2048. Some KDF implementations
require an iteration count.
- -iv string
- Initialization vector (IV) to use. Required for some ciphers and GMAC.
Other MACs use a fixed IV. Cipher modes CBC, CFB, and OFB all need an IV,
while ECB and CTR modes do not. A new, random IV should (must for OFB) 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.
- -key string
- 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 <
key_length it will be padded. Max is 64 bytes. If > key_length,
it will be rejected.
See the tls::cipher for key_length.
- -mac name
- Name of Message Authentication Code (MAC) to use.
See tls::macs command for the valid values.
- -padding boolean
- Specifies whether to use PKCS#7 padding or not for block ciphers. If
true, 1 to block size number of pad bytes will be added to the output to
pad to the next block size. Default is true.
- -password string
- 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 -key option.
- -properties list
- List of additional properties to pass to cryptographic function.
- -salt string
- 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.
- -length integer
- -size integer
- Set the output length in bytes. Used by KDFs, KMAC128 and KMAC256 MACs,
and SHAKE128 and SHAKE256 XOF hashes. The default length for KMAC128 is 32
bytes and KMAC256 is 64 bytes. The default length for SHAKE128 is 16 bytes
and SHAKE256 is 32 bytes.
- -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.
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
set data ""
while {![eof $ch]} {append data [read $ch 4096]}
close $ch
puts $data
- -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]
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
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 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. 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 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.
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.
These commands provide information about the available ciphers, digests, etc. and their properties.
- tls::cipher name
- Returns a list of property name and value pairs describing cipher
name. Properties are:
| nid | Internal id of cipher. This is the same as name. | |
| name | Name or alias of the cipher. | |
| description | Description of the cipher. OpenSSL 3.0+ only. | |
| block_size | Block size of the cipher. Stream ciphers are set to 1. | |
| key_length | key length of a cipher in bytes. | |
| iv_length | IV length of a cipher in bytes or 0 if not used. | |
| type | Base type of this cipher or undefined if none. | |
| provider | Provider of the cipher. OpenSSL 3.0+ only. | |
| mode | Block cipher mode or stream for a stream cipher. | |
| flags | Flags 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
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 name and value
pairs describing message digest name. Properties are:
| name | Name or alias of the digest. | |
| description | Description of the digest. OpenSSL 3.0+ only. | |
| size | Size of the digest in bits. | |
| block_size | Block size of digest in bytes. | |
| provider | Provider of the digest. OpenSSL 3.0+ only. | |
| type | Base type of this digest or undefined if none. | |
| pkey_type | Pkey associated with digest. | |
| flags | Flags associated with the digest. Includes:
One-shot (only one update (no incremental) allowed), XOF (variable length), etc. | |
- tls::kdfs
- Returns a list of the available Key Derivation Function (KDF)
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).
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
compile time flags.
- tls::version
- Returns the OpenSSL version string.
These commands calculate a message digest or message authentication code for data.
- tls::cmac
?-cipher? name
-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::digest
option value ...
- Alias for tls::md.
- tls::hash
option value ...
- Alias for tls::md.
- tls::hmac
?-digest? name
-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?
?-length|-size length?
[-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?
?-length|-size length?
[-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.
- 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.
These commands encrypt plaintext into ciphertext or vice versa.
- tls::encrypt
?-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 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 |
-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.
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).
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?
?-length|-size length?
- Derive a key of size length using the HMAC-based Extract-and-Expand
Key Derivation Function (HKDF).
See options for usage info.
- tls::pbkdf2
[-cipher cipher |
-length 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.
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 length bytes is returned.
- tls::scrypt
-password string
-salt string
?-N costParameter?
?-r blockSize?
?-p parallelization?
?-length|-size length?
- Derive a key of size length 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:
| -N | The CPU/Memory cost parameter
must be larger than 1, a power of 2, and less than
2^(128 * r / 8). Default is 1048576. | |
| -r | The blockSize parameter specifies the
block size. Must be greater than 0. Default is 8. | |
| -p | The parallelization parameter
must be a positive integer less than or equal
to ((2^32-1) * 32) / (128 * r). Default is 1. | |
These commands provide randomly generated byte strings for use when random data is needed.
- tls::random
?-private? length
- Generate length random bytes using a cryptographically secure
pseudo random generator (CSPRNG). OpenSSL uses a security level of 256
bits. Will return an error if a trusted entropy source such as the OS
isn't available. Use -private option if the values are intended
to remain private in case the public PRNG is compromised.
These commands provide access to the OpenSSL providers.
- tls::provider
name
- Load name default provider. Valid provider names are:
default, base, fips, and legacy. Use
legacy to load the legacy provider ciphers, digests, etc.
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.
| AAD | Additional Authenticated Data |
| AEAD | Authenticated Encryption with Associated Data |
| AES | Advanced Encryption Standard |
| CBC | AES Cipher Block Chaining mode |
| CFB | AES Cipher Feedback mode |
| CTR | AES Counter mode |
| ECB | AES Electronic Codebook mode |
| IV | Initialization vector |
| KDF | Key Derivation Function |
| MAC | Message Authenticated Code |
| MD | Message Digest |
| OFB | AES Output Feedback mode |
| SHA | Secure Hash Algorithm |
| SSL | Secure Sockets Layer |
| TLS | Transport Layer Security |
| XOF | Extendable-Output Function (aka variable length) |
TBS
TBD
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.