The Tcl Cryptography Package

ADDED doc/cryptography.html Index: doc/cryptography.html ================================================================== --- /dev/null +++ doc/cryptography.html @@ -0,0 +1,404 @@ + + + + + +The Tcl Cryptography Package + + + + + +

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

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
+

+ +
+

OPTIONS

+ +

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.

+ +
+

COMMANDS

+ +

The following commands provide access to the OpenSSL cryptography functions.

+ +

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

+ +
+

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

+ + ADDED doc/docs.css Index: doc/docs.css ================================================================== --- /dev/null +++ doc/docs.css @@ -0,0 +1,1 @@ +body,div,p,th,td,li,dd,ul,ol,dl,dt,blockquote{font-family:Verdana,sans-serif}pre,code{font-family:courier new,Courier,monospace}pre{background-color:#f6fcec;border-top:1px solid #6a6a6a;border-bottom:1px solid #6a6a6a;padding:1em;overflow:auto}body{background-color:#fff;font-size:12px;line-height:1.25;letter-spacing:.2px;padding-left:.5em}h1,h2,h3,h4{font-family:Georgia,serif;padding-left:1em;margin-top:1em}h1{font-size:18px;color:#11577b;border-bottom:1px dotted #11577b;margin-top:0}h2{font-size:14px;color:#11577b;background-color:#c5dce8;padding-left:1em;border:1px solid #6a6a6a}h3,h4{color:#1674a4;background-color:#e8f2f6;border-bottom:1px dotted #11577b;border-top:1px dotted #11577b}h3{font-size:12px}h4{font-size:11px}.keylist dt,.arguments dt{width:20em;float:left;padding:2px;border-top:1px solid #999}.keylist dt{font-weight:700}.keylist dd,.arguments dd{margin-left:20em;padding:2px;border-top:1px solid #999}.copy{background-color:#f6fcfc;white-space:pre;font-size:80%;border-top:1px solid #6a6a6a;margin-top:2em}.tablecell{font-size:12px;padding-left:.5em;padding-right:.5em} Index: doc/tls.html ================================================================== --- doc/tls.html +++ doc/tls.html @@ -1,53 +1,42 @@ - - - - + + -TLS (SSL) Tcl Commands +TLS (SSL) TCL Commands + - + + +

Tcl Tls Extension Documentation

NAME

tls - binding to OpenSSL toolkit.

tls - binding to OpenSSL library + for socket and I/O channel communications.

SYNOPSIS

package require Tcl ?8.4?; package require Tcl ?8.5?; package require tls
: tls::init ?options?; tls::socket ?options? host port; tls::socket ?-server command? ?options? port; tls::socket ?-server command? ?options? port; tls::handshake channel; tls::status ?-local? channel; tls::connection channel; tls::status ?-local? channel; tls::connection channel; tls::import channel ?options?; tls::unimport channel
: tls::cipher name; tls::ciphers ?protocol? ?verbose? ?supported?; tls::digests ?name?; tls::macs; tls::protocols; tls::version
: tls::digest -digest name ?options?; tls::cmac -cipher name -key key ?options?; tls::hmac -digest name -key key ?options?; tls::md4 data; tls::md5 data; tls::sha1 data; tls::sha256 data; tls::sha512 data

COMMANDS

CALLBACK OPTIONS

HTTPS EXAMPLE

NAME

tls - binding to OpenSSL -toolkit.

tls - binding to OpenSSL library +for socket and I/O channel communications.

SYNOPSIS

package require Tcl 8.5
package require tls
@@ -74,25 +63,12 @@ tls::connection channel
tls::handshake channel
tls::import channel ?options?
tls::unimport channel

-tls::cipher name
-tls::ciphers ?protocol? ?verbose? ?supported?
-tls::digests ?name?
-tls::macs
tls::protocols
tls::version
-
-tls::digest -digest name ?options?
-tls::cmac -cipher name -key key ?options?
-tls::hmac -digest name -key key ?options?
-tls::md4 data
-tls::md5 data
-tls::sha1 data
-tls::sha256 data
-tls::sha512 data

DESCRIPTION

This extension provides a generic binding to

tls::socket ?-server command? ?options? port

This is a helper function that utilizes the underlying commands (tls::import). It behaves exactly the same as the native Tcl socket - command except that the options can include any of the + command except the options can also include any of the applicable tls:import options with one additional option:

-autoservername bool
-
Automatically send the -servername as the host argument - (default is false)
+
Automatically set the -servername argument to the host + argument (default is false).

tls::import channel ?options?

SSL-enable a regular Tcl channel - it need not be a - socket, but must provide bi-directional flow. Also - setting session parameters for SSL handshake.

Add SSL/TLS encryption to a regular Tcl channel. It need + not be a socket, but must provide bi-directional flow. Also + set session parameters for SSL handshake.

-alpn list

List of protocols to offer during Application-Layer @@ -161,11 +137,11 @@
-cert filename

Specify the contents of a certificate to use, as a DER encoded binary value (X.509 DER).

-cipher string

List of ciphers to use. String is a colon (":") separated list - of ciphers or cipher suites. Cipher suites can be combined + of ciphers. Ciphers can be combined using the + character. Prefixes can be used to permanently remove ("!"), delete ("-"), or move a cypher to the end of the list ("+"). Keywords @STRENGTH (sort by algorithm key length), @SECLEVEL=n (set security level to n), and DEFAULT (use default cipher list, at start only) @@ -173,11 +149,11 @@ list of valid values. (TLS 1.2 and earlier only)

-ciphersuites string

List of cipher suites to use. String is a colon (":") separated list of cipher suite names. (TLS 1.3 only)

-command callback
-
Callback to invoke at several points during the handshake. +
Callback command to invoke at several points during the handshake. This is used to pass errors and tracing information, and it can allow Tcl scripts to perform their own certificate validation in place of the default validation provided by OpenSSL. See CALLBACK OPTIONS for further discussion.
@@ -191,12 +167,12 @@
-model channel

Force this channel to share the same SSL_CTX structure as the specified channel, and therefore share callbacks etc.

-password callback
-
Callback to invoke when OpenSSL needs to obtain a password, - typically to unlock the private key of a certificate. The +
Callback command to invoke when OpenSSL needs to obtain a password. + Typically used to unlock the private key of a certificate. The callback should return a string which represents the password to be used. See CALLBACK OPTIONS for further discussion.

-post_handshake bool

Allow post-handshake ticket updates.
@@ -204,26 +180,29 @@
Request a certificate from peer during SSL handshake. (default is true)

-require bool

Require a valid certificate from peer during SSL handshake. If this is set to true, then -request must - also be set to true. (default is false)
+ also be set to true and a either a -cadir, -cafile, or platform + default must be provided in order to validate against. + (default is false)
-security_level integer

Set security level. Must be 0 to 5. The security level affects - cipher suite encryption algorithms, supported ECC curves, + the cipher suite encryption algorithms, supported ECC curves, supported signature algorithms, DH parameter sizes, certificate key sizes and signature algorithms. The default is 1. Level 3 and higher disable support for session tickets and only accept cipher suites that provide forward secrecy.

-server bool
-
Handshake as server if true, else handshake as - client. (default is false)
+
Set to act as a server and respond with a server handshake when + a client connects and provides a client handshake. + (default is false)

-servername host
-
Specify server hostname. Only available if the OpenSSL library - the package is linked against supports the TLS hostname extension - for 'Server Name Indication' (SNI). Use to name the logical host - we are talking to and expecting a certificate for.
+
Specify server's hostname. Used to set the TLS 'Server Name + Indication' (SNI) extension. Set to the expected servername + in the server's certificate or one of the subjectAltName + alternates.

-session_id string

Session id to resume session.

-ssl2 bool

Enable use of SSL v2. (default is false)

-ssl3 bool
@@ -235,44 +214,44 @@
-tls1.2 bool

Enable use of TLS v1.2 (default is true)

-tls1.3 bool

Enable use of TLS v1.3 (default is true)

-validatecommand callback
-
Callback to invoke to verify or validate protocol config +
Callback command to invoke to verify or validate protocol config parameters during the protocol negotiation phase. See CALLBACK OPTIONS for further discussion.

tls::unimport channel

Provided for symmetry to tls::import, this - unstacks the SSL-enabling of a regular Tcl channel. An error + unstacks the encryption of a regular Tcl channel. An error is thrown if TLS is not the top stacked channel type.

tls::handshake channel

tls::handshake + channel

Forces handshake to take place, and returns 0 if handshake is still in progress (non-blocking), or 1 if the handshake was successful. If the handshake failed this routine will throw an error.

tls::status ?-local? channel

Returns the current status of the certificate for an SSL - channel. The result is a list of key-value pairs describing - the certificate. If the SSL handshake has not yet completed, - an empty list is returned. If -local is - specified, then the local certificate is used.

Returns the current status of an SSL channel. The result is a list + of key-value pairs describing the SSL, certificate, and certificate + verification status. If the SSL handshake has not yet completed, + an empty list is returned. If -local is specified, then the + local certificate is used.

SSL Status

alpn protocol

The protocol selected after Application-Layer Protocol Negotiation (ALPN).

cipher cipher
-
The current cipher in use between the client and - server channels.
+
The current cipher in use between for the channel.

peername name

The peername from the certificate.

protocol version

The protocol version used for the connection: SSL2, SSL3, TLS1, TLS1.1, TLS1.2, TLS1.3, or unknown.
@@ -300,11 +279,11 @@
Dump of all certificate info.

version value

The certificate version.

serialNumber n
-
The serial number of the certificate as hex string.
+
The serial number of the certificate as a hex string.

signature algorithm

Cipher algorithm used for certificate signature.

issuer dn

The distinguished name (DN) of the certificate issuer.

notBefore date
@@ -324,14 +303,14 @@
Number of certificate extensions.

extensions list

List of certificate extension names.

authorityKeyIdentifier string

(AKI) Key identifier of the Issuing CA certificate that signed - the SSL certificate as hex string. This value matches the SKI + the SSL certificate as a hex string. This value matches the SKI value of the Intermediate CA certificate.

subjectKeyIdentifier string
-
(SKI) Hash of the public key inside the certificate as hex +
(SKI) Hash of the public key inside the certificate as a hex string. Used to identify certificates that contain a particular public key.

subjectAltName list

List of all of the alternative domain names, sub domains, and IP addresses that are secured by the certificate.
@@ -340,36 +319,35 @@
certificate cert

The PEM encoded certificate.

signatureAlgorithm algorithm
-
Cipher algorithm used for certificate signature.
+
Cipher algorithm used for the certificate signature.

signatureValue string
-
Certificate signature as hex string.
+
Certificate signature as a hex string.

signatureDigest version
-
Certificate signing digest.
+
Certificate signing digest as a hex string.

publicKeyAlgorithm algorithm

Certificate signature public key algorithm.

publicKey string
-
Certificate signature public key as hex string.
+
Certificate signature public key as a hex string.

bits n
-
Number of bits used for certificate signature key
+
Number of bits used for certificate signature key.

self_signed boolean
-
Is certificate signature self signed.
+
Whether the certificate signature is self signed.

sha1_hash hash
-
The SHA1 hash of the certificate as hex string.
+
The SHA1 hash of the certificate as a hex string.

sha256_hash hash
-
The SHA256 hash of the certificate as hex string.
+
The SHA256 hash of the certificate as a hex string.

tls::connection channel

Returns the current connection status of an SSL channel. The - result is a list of key-value pairs describing the - connected peer.

SSL Status

state state

State of the connection.
@@ -406,12 +384,12 @@
secret_bits n

The number of secret bits used for cipher.

min_version version

The minimum protocol version for cipher.

cipher_is_aead boolean
-
Whether the cipher is Authenticated encryption with associated - data (AEAD).
+
Whether the cipher is Authenticated Encryption with + Associated Data (AEAD).

cipher_id id

The OpenSSL cipher id.

description string

A text description of the cipher.

handshake_digest boolean
@@ -423,11 +401,11 @@

alpn protocol

The protocol selected after Application-Layer Protocol Negotiation (ALPN).

resumable boolean
-
Can the session be resumed or not.
+
Whether the session can be resumed or not.

start_time seconds

Time since session started in seconds since epoch.

timeout seconds

Max duration of session in seconds before time-out.

lifetime seconds
@@ -443,137 +421,18 @@
session_cache_mode mode

Server cache mode (client, server, or both).

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 ciphers. 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 hash algorithms - for tls::digest command. With name, returns a list of - property names and values describing digest name. Properties - include name, description, size, block_size, type, and flags list.

tls::macs

Returns a list of the available Message Authentication Codes (MAC) for - the tls::digest command.

tls::protocols

Returns a list of supported protocols. Valid values are: +

Returns a list of the 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.

tls::digest -digest - name ?-bin|-hex? [-file filename | -command cmdName | - -chan channelId | -data data]

Calculate the message digest (MD) of data using name hash - function and return the resulting hash value as a hex string (default) - or as a binary value with -bin or -binary option. MDs - are used to ensure the integrity of data. The hash function can be any - supported OpenSSL algorithm such as md4, md5, sha1, - sha256, sha512, sha3-256, etc. See - tls::digests command for a full list. In OpenSSL 3.0+, older - algorithms may reside in the legacy provider. -
- Using the -data option will immediately return the message - digest for data in the specified format. Example code: -

- set md [::tls::digest sha256 "Some example data."] -

- Using the -file or -filename option will open file - filename, read the file data, close the file, and return the - message digest in the specified format. This uses the TCL APIs, so VFS - files are supported. Example code: -

- set md [::tls::digest -digest sha256 -file test_file.txt] -

- Using the -chan or -channel option, a stacked channel is - created for channelId and data read from the channel is used - to calculate a message digest with the result returned with the last - read operation before EOF. Channel is automatically set to binary mode. - Example code: -

- set ch [open test_file.txt r] - ::tls::digest -digest sha256 -chan $ch - while {![eof $ch]} {set md [read $ch 4096]} - close $ch -

- Using the -command option, a new command cmdName is - created and returned. To add data to the hash function, call - "cmdName update data", where data is - the data to add. When done, call "cmdName finalize" - to return the message digest. Example code: -

- set cmd [::tls::digest -digest sha256 -command ::tls::temp] - $cmd update "Some data. " - $cmd update "More data." - set md [$cmd finalize] -

tls::cmac -cipher name - -key key ?-bin|-hex? [-file filename | -command cmdName | - -chan channelId | -data data]

Calculate the Cipher-based Message Authentication Code (CMAC). MACs - are used to ensure authenticity and the integrity of data. It uses the - same options as tls::digest, plus the additional option - -cipher to specify the cipher to use and for certain ciphers, - -key to specify the key.

tls::hmac -digest name - -key key ?-bin|-hex? [-file filename | -command cmdName | - -chan channelId | -data data]

Calculate the Hash-based Message Authentication Code (HMAC). HMACs are - used to ensure the data integrity and authenticity of a message using a - shared secret key. The cryptographic strength depends upon the size of - the key and the security of the hash function used. It uses the same - options as tls::digest, plus additional option -key to - specify the key to use. To salt a password, append or prepend the salt - data to the password.

tls::mac -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). MACs - are used to ensure authenticity and the integrity of data. It uses the - same options as tls::digest, plus the additional options - -cipher to specify the cipher to use, -digest to specify - the digest, and for certain ciphers, -key to specify the key.

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.

CALLBACK OPTIONS

@@ -580,11 +439,11 @@ As indicated above, individual channels can be given their own callbacks to handle intermediate processing by the OpenSSL library, using the -command, -password, and -validate_command options passed to either of tls::socket or tls::import. -If the callback generates an error, the bgerror command with be +If the callback generates an error, the bgerror command will be invoked with the error information.

@@ -788,41 +647,41 @@ to call tls::password. The difference between these two behaviors is a consequence of maintaining compatibility with earlier implementations.
-
-The tls::debug variable provides some additional -control over these reference callbacks. Its value is zero by default. -Higher values produce more diagnostic output, and will also force the -verify method in tls::callback to accept the -certificate, even when it is invalid. -
-
The use of the reference callbacks tls::callback, tls::password, and tls::validate_command is not recommended. They may be removed from future releases.
-
- -The use of the variable tls::debug is not recommended. -It may be removed from future releases. - -
-
DEBUG
TLS key logging can be enabled by setting the environment variable SSLKEYLOGFILE to the name of the file to log to. Then whenever TLS key material is generated or received it will be logged to the file. This is useful for logging key data for network logging tools to use to decrypt the data. +
+The tls::debug variable provides some additional +control over these reference callbacks. Its value is zero by default. +Higher values produce more diagnostic output, and will also force the +verify method in tls::callback to accept the +certificate, even when it is invalid. +
+ +
+ +The use of the variable tls::debug is not recommended. +It may be removed from future releases. + +
+
HTTPS EXAMPLE

This example uses a sample server.pem provided with the TLS release, courtesy of the OpenSSL project.
@@ -835,15 +694,15 @@ 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 -protocol versions, add or remove ciphers, change default values, etc. Use the -tls::ciphers and tls::protocols commands to -obtain the supported versions.
+
The capabilities of this package can vary enormously based upon how the +linked to OpenSSL library was configured and built. New versions may obsolete +older protocol versions, add or remove ciphers, change default values, etc. +Use the tls::protocols commands to obtain the supported +protocol versions.

SEE ALSO

socket, fileevent, OpenSSL

Tcl Cryptography Documentation

NAME

DESCRIPTION

SYNOPSIS

OPTIONS

Cryptographic Options

Input/Output Options

Format Options

COMMANDS

Info Commands

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

GLOSSARY

EXAMPLES

SPECIAL CONSIDERATIONS

Tcl Tls Extension Documentation

NAME

SYNOPSIS

DESCRIPTION

CALLBACK OPTIONS

DEBUG

HTTPS EXAMPLE

SPECIAL CONSIDERATIONS

SEE ALSO