Package: tlsmate
tlsmateOverviewThis project provides a python framework for simulating TLS endpoints. It
provides a comfortable way of creating arbitrary TLS handshake scenarios and
executes the scenarios against TLS servers or clients (well, at the current
state of the project only client simulations are supported).A plugin is provided which scans a TLS server for its configurations (i.e.,
support of TLS protocol versions, cipher suites, and much more) as well as for
some commonly known TLS vulnerabilities.A word of warningThis package is intended for test purposes only. Never ever use it to
transmit sensitive data! Here are some reasons:secret keying material isn’t appropriately protected, e.g., it is not deleted
when not used anymore. Such sensitive data are even logged for debugging purpose.quite a lot of checks are missing which are essential for productive use cases.random valuesare not always randomSide channels? Definitely. Constant time implementation? No.Extensive tests and proven in practice? No!etc.Featurestlsmatecomes with its own TLS protocol stack implementation. For a list of
supported TLS protocol elements refer toTLS features.The following basic features are supported:TLS versions: SSLv2 (rudimentary only), SSLv3, TLS1.0, TLS1.1, TLS1.2, TLS1.3arbitrary L4-ports are supportedcustomized trust store for root certificatesclient authenticationcertificate revocation check by CRL and via OCSPscan result is provided as JSON/Yaml format to simplify tool-based post-processingplugin concept for either proprietary test cases or for extending the scanner pluginwriting keying material to a key logging file to allow wireshark to decode encrypted packetsconfiguration oftlsmatethrough an ini-file or through environment variablesslowing down a scan to circumvent rate limitingsseveral logging levelsHTTP-proxy supportDocker image providedFor creating customized handshake scenarios the following features are provided:TLS messages can be sent/received in any arbitrary orderall TLS message parameters can be set to any arbitrary valuesending and receiving application datapredefined client profiles (legacy, interoperability, modern, TLS1.3-only)basic settings (version, ciphersuites, etc.) can be taken from the server profile to
minimize interoperability issues with the serverdifferent levels for defining a handshake: from a one liner for the complete handshake
to defining the deepest bit in a messagevarious conditions when waiting for a message (timeout, optional message)background handling of some messages (e.g., NewSessionTicket)simple python API to usetlsmatefrom other python applicationsThe following features are currently not yet supported but will likely be added
in the future:simulating a TLS server (thus allowing to test TLS clients)InstallationThis package requires Python3.6 or higher. The recommended way installingtlsmateis using pip:$pipinstalltlsmateIn case this does not work, check if the problem is caused by the cryptographic
librarycryptography, and refer toInstallation of cryptography.Minimal configurationBy defaulttlsmatecomes with an empty trust store, and thus all
certificate chain validations will fail.There are two different ways recommended to configure the trust store.Using the system’s set of root certificatesIn case the root CA certificates are installed on the system, their location
depend on the OS. Ifopensslis installed on the system, use the following
command:$opensslversion-dThis will print the openssl directory, e.g./usr/lib/ssl. The certificates
are located in the subdirectorycerts, and there typically a file is
provided which contains all certificates concatenated. On Ubuntu, this file
is namedca-certificates.crt, on CentOS the name isca-bundle.crt.This file needs to be configured in the tlsmate-ini file,see below.Download the Mozilla root CA certificatesAs an alternative the root CA certificates used by Mozilla can be used.
Download the file and calculate its SHA256 checksum:$curl-s-ocacert.pemhttps://curl.se/ca/cacert.pem&&sha256sumcacert.pemCompare the SHA256 hash value with the value provided athttps://curl.se/ca/cacert.pem.sha256.If the value matches, configure the downloaded file in the tlsmate-ini file, see below.Configuring the trust store in the .tlsmate.ini fileLet’s assume the name of the trust store file is/usr/lib/ssl/certs/ca-certificates.crt.
Now create a new ini file in your home directory:$echo-e"[tlsmate]\nca_certs = /usr/lib/ssl/certs/ca-certificates.crt">~/.tlsmate.ini$cat~/.tlsmate.ini[tlsmate]
ca_certs = /usr/lib/ssl/certs/ca-certificates.crtNoteThis command will overwrite an existing ini file. Adapt the command or
use your favorite editor if you want to keep the existing file.More information on the use of ini-files is providedhere.Basic usageFor a full documentation of thetlsmatecommand refer to thedocumentation
here. There you will find a
detailed description how to use the package directly from other python
applications.In the following only some basic examples for using the CLI are
given. Use thetlsmate--helpcommand to get all supported subcommands.NoteIn the example the domain name “mytlsmatedomain.net” is used, which is
currently not registered. Replace it with the domain name you want to use.$tlsmatescan--progressmytlsmatedomain.netThis command will perform a TLS scan against the domainmytlsmatedomain.net, and the
result will be displayed as colored console output. For an example refer to theoutput of the scan command.If you want to use the provided Docker container instead, use the following
command:$dockerrun-itguballa/tlsmatetlsmatescan--progressmytlsmatedomain.netNoteThe docker image has the trust store preconfigured, therefore the
configuration as described above is not required.Using the tlsmate library from other python applications is described in thePython API documentation.