CHALO TLS Interposer (tlsinterposer)

The CHALO TLS Interposer (tlsinterposer) is a benign sofware tool that places itself in the middle of TLS communications with the goal of upgrading the TLS version used during the TLS protocol. In short, users can specify the target of the communication (using the IP address) and tlsinterposer will follow a man-in-the-middle approach and intercept the TLS protocol to infer the TLS version and the ciphersuites being negotiated and, if needed, negotiate a higher version that is more secure and that is not vulnerable to known attacks.

Dependencies

To install tlsinterposer, it is necessary to build a dedicated openssl and python versions. We provide detailed instructions to correctly install them to be used in tlsinterposer.

OpenSSL

Because we want support for deprecated TLS version, we need to build OpenSSL with support for deprecated TLS ciphersuites. The following instructions have been successefully tested with an Ubuntu 25.04 and OpenSSL 3.5.2.

1 - Clone the openssl repository

$> git clone  

2 - Checkout the 3.5.2 release

$> cd openssl
$> git checkout tags/openssl-3.5.2

3 - Create a build directory to store the OpenSSL installation

$> mkdir build

4 - Configure OpenSSL with support for deprecated TLS ciphersuites and old algorithms

$> ./Configure --prefix=PATH_TO_OPENSSL/build enable-weak-ssl-ciphers enable-md2 enable-rc5

and replace PATH_TO_OPENSSL with the path to the OpenSSL repositorty

5 - Build OpenSSL and install it locally in PATH_TO_OPENSSL/build with

$> make
$> make install

6 - These commands should populate the build folder with a bin, include, lib, share and ssl folders. Now it is required to change the build/ssl/openssl.cnf file

$> cd build/ssl

and edit the file with your favorite text editor as follows:

• In the [openssl_init] section, add the following line ssl_conf = ssl_configuration bellow providers = provider_sect.

• Then, add the following text to the end of the file

  [ssl_configuration]
  system_default = tls_system_default
  
  [tls_system_default]
  MinProtocol = TLSv1
  CipherString = DEFAULT@SECLEVEL=0
  Options = UnsafeLegacyRenegotiation
  

This changes the OpenSSL configuration to support deprecated TLS versions.

Python

Next, install Python referring to the OpenSSL installation that we just completed. The following instructions have been successefully tested with Python 3.12.3.

1 - Clone the cpython repository

$> git clone  

2 - Checkout the 3.12.3 release

$> cd cpython
$> git checkout tags/

3 - Create a build directory to store the Python installation

$> mkdir build

4 - Configure Python referring to the local OpenSSL installation

./configure --prefix=PATH_TO_CPYTHON/build/ --with-openssl=PATH_TO_OPENSSL/build/ --with-openssl-rpath=PATH_TO_OPENSSL/build/lib/ --with-ssl-default-suites=openssl

and replace PATH_TO_OPENSSL with the path to the OpenSSL repositorty and PATH_TO_CPYTHON with the path to cpython repository.

5 - Install the following external dependencies

$> sudo apt install build-essential gdb lcov pkg-config libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev libncurses5-dev libsqlite3-dev libssl-dev lzma tk-dev uuid-dev zlib1g-dev libreadline6-dev libmpdec-dev

6 - Build Python and install it locally in PATH_TO_CPYTHON/build with

$> make
$> make install

Installing tlsinterposer

To build and execute tlsinterposer, we highly recommend using virtualenv.

1 - First, install virtualenv

$> sudo apt install virtualenv

2 - Create a virtual environment for the previous Python installation.

$> virtualenv -p PATH_TO_CPYTHON/build/bin/python3.13 tlsinterposer-venv

3 - Activate the virtual environment that you just created

$> source tlsinterposer-venv/bin/activate

4 - Install Python dependencies netns and setuptools

$> pip install netns setuptools

5 - Install tlsinterposer locally inside the virtual environment by running

$> python setup.py install

This creates a tlsinterposer binary at tlsinterposer-venv/bin/.

Running tlsinterposer

tlsinterposer can now be executed by

sudo tlsinterposer-venv/bin/tlsinterposer --target TARGET_IP:443

and replace TARGET_IP with the desired IP address.

tlsinterposer tests

To test tlsinterposer, we disclose two IP addresses that still use TLS 1.0 and that can be used to demonstrate tlsinterposer capabilities.

sudo tlsinterposer-venv/bin/tlsinterposer --target 208.93.184.7:443
sudo tlsinterposer-venv/bin/tlsinterposer --target :443

Contributing

Contributions to this repository are greatly appreciated. If you are interested, please adhere to the following guidelines:

1. To add, update, or delete information from this repository, please submit a pull request (PR) and assign a reviewer to your PR.

2. In your PR, please state why the new functionality is relevant to the tool.

3. Make sure you adhere to the guidelines and existing format of the repository.

Citation

If you find tlsinterposer useful in your research, please cite it using the data on CITATION.cff file.

License

This work has been released under an MIT License. See LICENSE for additional information.

Contact

For any questions regarding this project, please contact Briland Hitaj and Vitor Pereira.