## 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
    tls::encrypt -cipher name -key key ?options?
    tls::decrypt -cipher name -key key ?options?
    tls::derive_key key ?options?
  OPTIONS
  COMMANDS
  GLOSSARY
  EXAMPLES
  SPECIAL CONSIDERATIONS

### NAME

tls - binding to OpenSSL toolkit.

### DESCRIPTION

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.

### 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
tls::encrypt -cipher name -key key ?options?
tls::decrypt -cipher name -key key ?options?
tls::derive_key ?options?

### OPTIONS

The following options are used by the cryptography commands.

#### Cryptographic Options

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

-digest name
  Name of hash function (aka message digest) to use. See tls::digests for the valid values.

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

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

-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 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
> set dat ""
> while {![eof $ch]} {append dat [read $ch 4096]}
> close $ch
> puts $dat`

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

### COMMANDS

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. If block-size is 1, then it's a stream cipher, otherwise it's a block cipher.
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? [-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 | -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 | -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 | -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.

#### 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).

#### Key Derivation Function (KDF) Commands

tls::derive_key [-cipher cipher | -size size] -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. 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.

### GLOSSARY

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.

### EXAMPLES

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

### SPECIAL CONSIDERATIONS

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.