tls - binding to OpenSSL -toolkit.
+tls - binding to OpenSSL library +for socket and I/O channel communications.
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
@@ -62,13 +63,12 @@
tls::connection channel
tls::handshake channel
tls::import channel ?options?
tls::unimport channel
-tls::ciphers protocol ?verbose? ?supported?
-tls::protocols
-tls::version
+tls::protocols
+tls::version
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 @@ -137,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) @@ -149,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.
@@ -167,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.
@@ -180,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
@@ -211,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.
@@ -276,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
@@ -300,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.
@@ -316,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.
@@ -352,51 +354,58 @@- 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-
- 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
@@ -412,22 +421,12 @@- session_cache_mode mode
- Server cache mode (client, server, or both).
@@ -648,40 +647,81 @@ 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 if the tls::validate_command +callback is used for the -validatecommand option. +
+ ++ +The use of the variable tls::debug is not recommended. +It may be removed from future releases. + +
+ +Example: ++ +Example #2: ++package require http +package require tls + +http::register https 443 [list ::tls::socket -autoservername true -require true -cadir /etc/ssl/certs \ + -command ::tls::callback -password ::tls::password -validatecommand ::tls::validate_command] + +set token [http::geturl "https://www.tcl-lang.org/"] +::http::cleanup $token +++package require tls + +set url "www.tcl-lang.org" +set port 443 + +set ch [tls::socket -autoservername 1 -servername $url -request 1 -require 1 \ + -alpn {http/1.1 h2} -cadir /etc/ssl/certs -command ::tls::callback \ + -password ::tls::password -validatecommand ::tls::validate_command $url $port] +chan configure $ch -buffersize 65536 +tls::handshake $ch + +puts $ch "GET / HTTP/1.1" +flush $ch +after 500 +set data [read $ch] + +array set status [tls::status $ch] +array set conn [tls::connection $ch] +array set chan [chan configure $ch] +close $ch +parray status +parray conn +parray chan +HTTPS EXAMPLE
This example uses a sample server.pem provided with the TLS release, courtesy of the OpenSSL project.
@@ -690,20 +730,21 @@ 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/] +set token [http::geturl https://www.tcl.tk/] +::http::cleanup $tokenSPECIAL 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