cltls - Man Page

Secure command-line tool to establish TLS sessions to selected hosts

Synopsis

cltls [Options] GET https://servername/path/to/resource[?query]

cltls [Options] GET servername /path/to/resource[?query]

cltls [Options] PUT https://servername/path/to/resource[?query] file

cltls [Options] PUT servername /path/to/resource[?query] file

cltls [Options] STORE servername

Description

cltls opens a TLS-1.2 session (or if that fails a TLS-1.3 session, if TLS-1.3 is allowed)  to a selected server and transferres any amount of data from the server (GET) or uploads the binary content of a file to the server (PUT).

cltls works under the assumption that the public key infrastructure used by browsers cannot always be trusted, because of a number of inherent problems with the PKI.

First, the sheer number of CAs trusted by browsers poses the risk of a rogue actor issuing a  fake certificate for a web server.  Generally, any CA can issue a certificate for any web server domain.  In contrast, cltls is build to restrict the number of trusted CAs to a very limited set of CAs that are positively known to work securely. This set of trusted CAs is under the end-user's sole control.

Second, some organisations or institutions may use their own (self-signed) web server certificates and want to restrict the TLS data transfer to members of their own organisation or  institution. With cltls the trusted use of internal web servers can be configured easily, making the use of any public key infrastructure completely obsolete.

There are two different authentication methods that are used by cltls to decide whether or not a TLS connection to a server will be established successfully. If the (SHA-2) fingerprint value of the server's certificate is found in the end-user's home directory under the server's domain name, the TLS session to the client will only be opened, if the  server presents exactly this certificate during the handshake, avoiding the use of any form of PKI.

The fingerprints (and certificates) can be stored with the STORE command in the user's home directory, but the verification of the certificate's validity must be performed with out-of-band first-hand knowledge. The server's name (or IP address) must be part of the certificate and it must match the server name given on the command line.

If there is no fingerprint value to be found, cltls tries to establish a TLS session and the certificate, which the server presents during the handshake, is then being checked with one of the CA root certificates that are stored in the end-user's home directory.  If this check fails or the relevant CA root certificate is not available, the TLS session terminates with the return code 3 (ERR_UNTRUSTED).

With these two mechanisms, fine-grained control over which servers can be accessed by the client  is guaranteed, as opposed to indistinguishably trusting any server certificate with the  widely-used PKI build into the operating system.

When both authentication methods have failed and the option "-ask" is used, the end-user is asked on the terminal to confirm (or deny) that the connection to this unauthenticated  server shall continue.

With the GET command, the data being retrieved from the selected server will be saved in a file under the directory ./servername , replicating the directory structure on the server. This default can be changed with the option "-stdout" in connection with "-silent", so that the data will be written to stdout exclusively.

With the option "-noout" the received data will not be written to the file system at all, which is needed, if only the connection information is being tested.

Options

-help

displays usage information and exits.

-silent

prints logging information into a log file instead of stdout.

-stdout

writes received bytes to stdout instead of writing to a file.

-noout

prevents writing of received bytes to a file.

-lts or -LTS

tries only to connect using TLS-1.2 with long term support.
(default is off)
see: https://www.ietf.org/archive/id/draft-gutmann-tls-lts-17.html

-redirect

allows redirection to a resource on the same already authenticated server.
(default is no redirection)

-debug

prints debugging information to stderr.

Files

$HOME/.cryptlib/certs/ServerName.hash

The 64 bytes SHA-2 fingerprint value of the server's certificate as a hexadecimal string. The existence of such a file disables all certificate checks. This method should only be used, if the server's certificate does not change frequently and has been verified reliably  with out-of-band information.

If the hash file does not exist, cltls checks the validity of the certificate during the TLS handshake.

$HOME/.cryptlib/certs/trusted/IssuerName.cert  or  $HOME/.cryptlib/certs/trusted/IssuerName.pem

A root CA's certificate which is needed for the web server authentication when no fingerprint is available. The IssuerName is taken from the last issuer DN in the certificate chain, and all space bytes are deleted from the DN.

$HOME/.cryptlib/debug/cltls.log

Holds the program's logging information when the option "-silent" is used. (redirected from stdout)

$HOME/.cryptlib/cltls/result.header and $HOME/.cryptlib/cltls/result.data

Separate header and data files that have been received from an authenticated server.

./servername/path/to/resource

File name that is used to store the binary data being received with the GET command. If the user has no permission to write to ./ , $HOME/.cryptlib/cltls is used to store the data.

/lib64/libcl.so.3.4.9

The cryptlib library.

/usr/lib/python3.1x/site-packages/cryptlib_py.so

Bindings to the cryptlib library used by python3.

Bugs

Please report bugs to innovation@senderek.ie

Authors

cltls is written by Ralf Senderek <innovation@senderek.ie>.
Cryptlib is written and maintained by Peter Gutmann <pgut001@cs.auckland.ac.nz>

See Also

cryptlib, clkeys, claes, clrsa, clsmime

Info

July 2026 Cryptlib Tools