@@ -125,11 +125,11 @@
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
applicable tls:import
- options with one additional option:
+ options with one additional option:
- -autoservername bool
- Automatically send the -servername as the host argument
(default is false)
@@ -205,11 +205,11 @@
(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)
- - -securitylevel integer
+ - -security_level integer
- Set security level. Must be 0 to 5. The security level affects
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
@@ -254,15 +254,15 @@
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
+ ?-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 result is an empty list then the
- SSL handshake has not yet completed. If -local is
+ 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.
SSL Status
- alpn protocol
@@ -376,41 +376,48 @@
- servername name
- The name of the connected to server.
- protocol version
- The protocol version used for the connection:
SSL2, SSL3, TLS1, TLS1.1, TLS1.2, TLS1.3, or unknown.
- - renegotiation boolean
+ - renegotiation_allowed boolean
- Whether protocol renegotiation is supported or not.
- - securitylevel level
+ - security_level level
- The security level used for selection of ciphers, key size, etc.
- session_reused boolean
- Whether the session has been reused or not.
- is_server boolean
- Whether the connection is configured as a server (1) or client (0).
- compression mode
- Compression method.
- expansion mode
- Expansion method.
+ - caList list
+ - List of Certificate Authorities (CA) for X.509 certificate.
Cipher Info
- cipher cipher
- The current cipher in use for the connection.
- standard_name name
- The standard RFC name of cipher.
- - bits n
+ - algorithm_bits n
- The number of processed bits used for cipher.
- secret_bits n
- The number of secret bits used for cipher.
- min_version version
- The minimum protocol version for cipher.
- - id id
+ - cipher_is_aead boolean
+ - 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
+ - Digest used during handshake.
Session Info
@@ -472,53 +479,76 @@
- 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 for data using digest hash
- function. Returns value as a hex string (default) or as a binary value
- with -bin or -binary option. Digest can be any OpenSSL
- supported hash function including: md4, md5, sha1,
+ 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.
+ 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.
-
+ 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.
-
+ 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.
+ 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). Same arguments
- as tls::digest with additional option -cipher to specify the
- cipher to use and for certain ciphers, -key to specify the key.
+ -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 Hashed Message Authentication Code (HMAC). Same arguments
- as tls::digest with additional option -key to specify the
- key to use. To salt a password, append or prepend the salt
- data to the password.
+ -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::md4 data
- Returns the MD4 message-digest for data as a hex string.
- tls::md5 data