DIT is a DTLS MitM proxy implemented in Python 3. It can intercept, manipulate and suppress datagrams between two DTLS endpoints and supports psk-based and certificate-based authentication schemes (RSA + ECC).
DIT is a MitM proxy tool to intercept DTLS traffic.
It can intercept, manipulate and/or suppress DTLS datagrams between two DTLS endpoints. To achieve this, the machine DIT is running on has to be put in a MitM position with tools like arpspoof. DIT has been built with Python 3.8, utilizes scapy and python-mbedtls to process datagrams and supports a wide variety of cipher suites. It can handle PSK-based and certificate-based (RSA + ECC) authentication schemes and has been built and tested on Debian-based Linux operating systems like Ubuntu or Kali Linux.
DIT has been built to analyze traffic between IoT devices but can intercept any DTLS traffic in a local network. It has been tested and evaluated with OpenSSL and devices from the IKEA TRÅDFRI and Philips Hue series. DIT can print the decrypted datagram payload to stdout or write it into a logfile. The tool can be configured via CLI arguments or via a configuration file (./config/dit_config.yaml).
DIT works with raw sockets and needs to run with root privileges. You can install DIT by simply cloning the repository and installing the dependencies listed in requirements.txt
with elevated privileges.
git clone https://github.com/CountablyInfinite/dit
pip3 install -r requirements.txt
After cloning and installing the dependencies you can run the following command with elevated privileges to see if DIT has been installed successfully:
./dit.py -h
**************************
* ___ ___ _____ *
* | \ |_ _| |_ _| *
* | |) | | | | | *
* |___/ |___| |_| *
* *
* DTLS INTERCEPTION TOOL *
* *
**************************
usage: ./dit.py [optional arguments] start
check configuration stored in ./config/dit_config.yaml before running DIT.
edit the file or use optional command line arguments to override the default configuration.
DIT needs root privileges and custom iptable rules to work properly.
run DIT:
start run DIT with the current settings (args override config file settings)
target configuration:
-isi , --iot_srv_ip iot server ip address (listening service) to be intercepted (config file: 192.168.183.129)
-isp , --iot_srv_po iot server port to be intercepted. (config file: 1337)
-ici , --iot_cli_ip iot client ip address to be intercepted. (config file: 192.168.183.128)
interface configuration:
-eif , --ex_if_name external interface name (e.g. "eth0") to listen for incoming connections. (config file: ens33)
-lif , --lh_if_name local interface name (e.g. "lo") to communicate with local services. (config file: lo)
psk configuration:
-cid , --cli_id client identity to configure server and client handler with. (config file: Client_identity)
-psk , --pre_sh_key pre-shared key to configure server and client handler with. (config file: DIT_secret)
--ciphers [ ...] list of ciphers to use, separated by spaces. (config file: None)
certificate configuration:
-cer, --use_cert [FLAG] use certificates as a method of authentication (instead of a psk). (config file: False)
-ks , --key_size length of the RSA/ECC key in bits. (config file: 2048)
-ecc, --use_ecc [FLAG] use 521 bit ECC instead of RSA to generate a key pair. disables --key_size. (config file: False)
local services configuration:
-lci , --lh_cli_ip local ip address to start a client handler (DTLS server) on. (config file: 127.0.0.1)
-lcp , --lh_cli_po local port to start a client handler (DTLS server listener) on. (config file: 1338)
-lsi , --lh_srv_ip local ip address to connect a server handler (DTLS client) to. (config file: 127.0.0.1)
-lsp , --lh_srv_po local port to connect a server handler (DTLS client) to. (config file: 1339)
miscellaneous:
-ibl, --icmp_block [FLAG] automatically create an iptables rule to suppress icmp 'destination unreachable' messages
-o , --output_file append intercepted unencrypted messages to an output file
-v, --verbose [FLAG] increase verbosity to DEBUG level
-h, --help [FLAG] show this help text and exit
examples:
./dit.py -isi 192.168.0.1 -isp 1337 -ici 192.168.0.2 --ciphers TLS-PSK-WITH-AES-128-CCM-8 TLS-PSK-WITH-CHACHA20-POLY1305-SHA256 -psk DIT_secret start
./dit.py --iot_srv_ip 192.168.0.1 --iot_cli_ip 192.168.0.2 --use_cert --key_size 3072 --ciphers TLS-RSA-WITH-AES-128-GCM-SHA256 --verbose start
./dit.py -isi 192.168.0.1 -ici 192.168.0.2 --use_cert -ecc --output_file logfile.log --verbose start
this tool has been created for the purposes of academic research.
use responsibly and only when explicitly authorized.
DIT uses raw sockets and therefore needs to run with elevated (root) privileges.
DIT builds four proxy layers with scapy that are communicating between the external interface and the DTLS services running on localhost. To suppress upcoming "Destination unreachable" errors - that cause DIT to halt with an error - a custom iptables rule is necessary. You can generate it with the following command:
iptables -I OUTPUT -d localhost-ip -p icmp --icmp-type destination-unreachable -j DROP
The iptable rules can be set/unset automatically by using the --icmp_block argument when starting DIT.
./dit.py --icmp_block start
For DIT to work it has to be run from a MitM position. A MitM position can be achieved in many ways, one of them is by using the tool arpspoof (part of the dsniff tool suite). To gain a MitM position in a local network between the clients 192.168.0.1 and 192.168.0.2 you can use the following command:
arpspoof -i ens33 -t 192.168.0.1 -r 192.168.0.2
DIT can be configured via CLI arguments or via a configuration file (./config/dit_config.yaml). CLI arguments override settings stored in the configuration file. When calling ./dit.py -h
- as depicted in section 2.1 - DIT prints out the current configuration that has been read from the configuration file.
DIT comes with a default configuration you'll need to adapt before running an attack.
cat ./config/dit_config.yaml
# configure spoofing/sniffing targets
targets:
iot_srv_ip: 192.168.183.129
iot_srv_po: 1337
iot_cli_ip: 192.168.183.128
ciphers:
# if no ciphers are configured, DIT will offer all ciphersuites available with mbedTLS
#- TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384
#- TLS-PSK-WITH-AES-128-CCM-8
#- TLS-RSA-WITH-AES-128-GCM-SHA256
# configure interface names
interfaces:
ex_if_name: ens33
lh_if_name: lo
# configure psk options
psk:
cli_id: Client_identity
pre_sh_key: DIT_secret
# configure certificate options
certificate:
# default is RSA. "use_ecc" arg enables ECC and disables key_size
use_cert: False
key_size: 2048
use_ecc: False
# configure local dtls services
local_services:
lh_cli_ip: 127.0.0.1
lh_cli_po: 1338
lh_srv_ip: 127.0.0.1
lh_srv_po: 1339
targets:
interfaces:
psk:
certificate:
local services:
DIT can be configured via Command Line Arguments. The arguments are listed and described when calling ./dit.py -h
- as shown in section 2.1. Command Line Arguments override settings stored in the configuration file and are a fast way to adapt/test settings without changing the config file.
Refer to https://github.com/CountablyInfinite/dit/tree/master/doc