tlsmate 1.2.2

Simulate a TLS client and scan a TLS server

tlsmate

Overview

This 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 warning

This 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 values are not always random

• Side channels? Definitely. Constant time implementation? No.

• Extensive tests and proven in practice? No!

• etc.

Features

tlsmate comes with its own TLS protocol stack implementation. For a list of supported TLS protocol elements refer to TLS features .

The following basic features are supported:

• TLS versions: SSLv2 (rudimentary only), SSLv3, TLS1.0, TLS1.1, TLS1.2, TLS1.3

• arbitrary L4-ports are supported

• customized trust store for root certificates

• client authentication

• certificate revocation check by CRL and via OCSP

• scan result is provided as JSON/Yaml format to simplify tool-based post-processing

• plugin concept for either proprietary test cases or for extending the scanner plugin

• writing keying material to a key logging file to allow wireshark to decode encrypted packets

• configuration of tlsmate through an ini-file or through environment variables

• slowing down a scan to circumvent rate limitings

• several logging levels

• HTTP-proxy support

• Docker image provided

For creating customized handshake scenarios the following features are provided:

• TLS messages can be sent/received in any arbitrary order

• all TLS message parameters can be set to any arbitrary value

• sending and receiving application data

• predefined 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 server

• different levels for defining a handshake: from a one liner for the complete handshake to defining the deepest bit in a message

• various conditions when waiting for a message (timeout, optional message)

• background handling of some messages (e.g., NewSessionTicket)

• simple python API to use tlsmate from other python applications

The 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)

Installation

This package requires Python3.6 or higher. The recommended way installing tlsmate is using pip:

$ pip install tlsmate

In case this does not work, check if the problem is caused by the cryptographic library cryptography, and refer to Installation of cryptography.

Minimal configuration

By default tlsmate comes 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 certificates

In case the root CA certificates are installed on the system, their location depend on the OS. If openssl is installed on the system, use the following command:

$ openssl version -d

This will print the openssl directory, e.g. /usr/lib/ssl. The certificates are located in the subdirectory certs, and there typically a file is provided which contains all certificates concatenated. On Ubuntu, this file is named ca-certificates.crt, on CentOS the name is ca-bundle.crt.

This file needs to be configured in the tlsmate-ini file, see below.

Download the Mozilla root CA certificates

As an alternative the root CA certificates used by Mozilla can be used. Download the file and calculate its SHA256 checksum:

$ curl -s -o cacert.pem https://curl.se/ca/cacert.pem && sha256sum cacert.pem

Compare the SHA256 hash value with the value provided at https://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 file

Let’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.crt

Note

This 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 provided here.

Basic usage

For a full documentation of the tlsmate command refer to the documentation 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 the tlsmate --help command to get all supported subcommands.

Note

In the example the domain name “mytlsmatedomain.net” is used, which is currently not registered. Replace it with the domain name you want to use.

$ tlsmate scan --progress mytlsmatedomain.net

This command will perform a TLS scan against the domain mytlsmatedomain.net, and the result will be displayed as colored console output. For an example refer to the output of the scan command.

If you want to use the provided Docker container instead, use the following command:

$ docker run -it guballa/tlsmate tlsmate scan --progress mytlsmatedomain.net

Note

The 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 the Python API documentation.