tls - binding to OpenSSL -toolkit.
+tls - binding to OpenSSL library +for socket and I/O channel communications.
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
This extension provides a generic binding to
- -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).
- -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.
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.
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).
- set md [::tls::digest sha256 "Some example data."]
-
- set md [::tls::digest -digest sha256 -file test_file.txt]
-
- set ch [open test_file.txt r]
- ::tls::digest -digest sha256 -chan $ch
- while {![eof $ch]} {set md [read $ch 4096]}
- close $ch
-
- set cmd [::tls::digest -digest sha256 -command ::tls::temp]
- $cmd update "Some data. "
- $cmd update "More data."
- set md [$cmd finalize]
-@@ -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