AfonsoVilalonga / TorKameleon

A Tor Pluggable Transport that shields Tor users from passive and active correlation attacks by employing WebRTC-based covert channels and K-anonymization.
10 stars 0 forks source link
censorship censorship-circumvention covert-channel encapsulation evasion pluggable-transports tor traffic-encapsulation webrtc webrtc-based-covert-channel

TorKameleon

TorKameleon is a solution designed to protect Tor users with increased censorship resistance against powerful traffic correlation attacks carried out by global adversaries. The system is based on flexible K-anonymization input circuits that can support TLS tunneling and WebRTC-based covert channels before forwarding users' original input traffic to the Tor network. Our goal is to protect users from correlation attacks through machine learning between incoming user traffic and the observed traffic at different Tor network intermediate relays or outgoing traffic to destinations. TorKameleon is the first system to implement a Tor pluggable transport based on both parameterizable TLS tunneling or WebRTC-based covert channels. We have implemented the TorKameleon prototype and performed extensive validations to observe the correctness and experimental performance of the proposed solution in the Tor environment.

The design, implementation and evaluation of the system is also described in our Arxiv 2023 paper. (To be published in TrustCom 2023)

@inproceedings{vilalonga2023torkameleon,
  title={TorKameleon: Improving Tor’s censorship resistance with K-anonymization and media-based covert channels},
  author={Vilalonga, Afonso and Resende, Jo{\~a}o S and Domingos, Henrique},
  booktitle={2023 IEEE 22nd International Conference on Trust, Security and Privacy in Computing and Communications (TrustCom)},
  pages={1490--1495},
  year={2023},
  organization={IEEE}
}

This code was implemented in the context of the dissertation:

@mastersthesis{TorKameleon, 
 author       = {Afonso Vilalonga},
 title        = {TorKameleon-Improving Tor's censorship resistance with K-anonymization media morphing covert input channels},
 school       = {NOVA School of Science and Technology}, 
 year         = 2022, 
 month        = 9,
}

Repo Folders

The repository currently consists of four different folders:

Prerequisites

Depending on how the TorKameleon is used, different prerequisites are required. If the deployment files are used (strongly recommended):

When running TorKameleon with the jars (not recommended), the system has been tested with the following software versions:

Setup

In our experiments, we used a setup similar to the one shown in the figure above. There are five main components in this setup:

The setup can also be used without the Tor network component (TorKameleon Tor Bridge, Tor Middle Relay, and Tor Exit Relay) by forwarding traffic between the local machine and the proxy and from the proxy to the HTTP server, or without the proxy component by having the local machine forward traffic directly to the TorKameleon Tor Bridge.

Configuration

There are two main configurable components in the TorKameleon system: the TorKameleon core and the WebRTC-based application. It is also possible to configure the deployment files, but these are only configurations of the test deployment, which in turn are configurations of the two aforementioned components.

WebRTC Config Files

The WebRTC-based configuration files can be accessed via the folders PT/WebRTC/Bridge/public/config/ or PT/WebRTC/Client/public/config/. There is also a Signaling server that can be configured at PT/WebRTC/Signalling/config/.

The PT/WebRTC/Bridge/public/config/ configures the WebRTC-based web application in receiver mode (the web application that receives and accepts all incoming WebRTC connections to a TorKameleon Tor Bridge or TorKameleon Proxy). There are three configurable fields in the configuration file:

The PT/WebRTC/Client/public/config/ configures the WebRTC-based web application in initiator mode (the web application that starts the WebRTC connections received by a TorKameleon Tor Bridge or Proxy). The configuration file is the same as the first one, with three exceptions:

The Signaling server can also be configured, namely:

TorKameleon Core Config Files

There are two configurable files for the TorKameleon core: the network configuration file and the config.properties configuration file. They are both located in the PT/Config/ folder.

config.properties File

The config.properties is a file used to configure all possible configurations in the TorKameleon core system. It has the following properties:

network File

The addresses of the Proxies are configured in the network file. The Proxies should be added in the following format: IP-Encapsulation_method-Order_number, where IP is the IP of the Proxy, Encapsulation_method is the type of encapsulation to be used with this specific Proxy (s, i.e. streaming, or t, i.e. TLS), and Order_number is the number of the Proxy in the network file (the first in the file is 1, the second in the file is 2, etc.). The window.signalling_server property of the WebRTC web application in initiator mode follows the same order in the array as in the network file.

Configuration Examples

Examples of how to configure various components (proxies, bridges, clients, etc.) can be found in the Deployment folder or via the links below. Note: 0000 in the fields of the config.properties file means that the field is not used for this configuration. The volume field in each Docker compose file should be changed with the specific location of the code on the current machine.

Deployment

The deployment folder contains two folders, the /Deployment/Coturn/ folder and the /Deployment/Setup/ folder.

Coturn Folder

The Coturn folder contains the configuration file for configuring the Coturn TURN and STUN server. To deploy the Coturn server on a machine, the following command should be used, using the configuration file in the Coturn folder:

docker run -d --network=host -v $(pwd)/my.conf:/etc/coturn/turnserver.conf coturn/coturn

The coturn configuration file should be moved to the current directory.

Setup Folder

The setup folder has six different folders that have different operating modes of TorKameleon and provide different configurations of the system. To deploy each component, the following command must be run in the particular folder to be deployed:

docker compose up

Usage

TorKameleon is Docker-friendly and should be used in containers configured like those in the deployment folder. However, it can also be run on a machine without Docker by compiling the Maven project and running the jar file. Other deployments can be configured and we recommend users to check the deployment folder and test the different configurations for the system and operating modes.

Client

The client should only be run when the TorKameleon environment is set up. The client software is started by launching the client's maven project jar. The following command should be used:

java -jar name_of_jar mode arg1 arg2 ...

There are several modes of operation of the client software, and each mode may have different arguments. The following are the operating modes of the client software:

There are four files available for download: ../Files/large, ../Files/small, ../Files/earth.jpg and ../Files/book.pdf. There are also four protocols available: tcp, dtls, udp and tcp.

HTTP Server

It can be deployed as a hidden service or as a normal HTTP server. Both are deployed by running docker compose up and for the normal HTTP server it is automatically ready to receive requests. For the hidden service, it is ready as soon as the 100% line appears on the console.

The HTTP server has three open ports that can be configured in /Client/Config/config.properties. These are:

TorKameleon Tor Bridge

The TorKameleon Tor Bridge is deployed by running the docker compose up command and is ready to receive connections once the Tor software is ready (once the 100% line appears on the console).

TorKameleon Proxy

The TorKameleon Proxy is deployed by running the docker compose up command and is ready when the Tor software is ready (as soon as the 100% line appears on the screen).