TLSGatekeeper

TLSGatekeeper enforces compliance with a chosen TLS guideline to ensure that TLS clients establish secure and compliant connections. It leverages eBPF and XDP to parse incoming TLS server messages and verify whether they conform to the specified guideline.

TLSGatekeeper can alert on connections that use invalid parameters and, if configured, can actively block such non-compliant connections.

Installation

To use TLSGatekeeper, you need to install eBPF and Rust dependencies. This installation guide assumes your OS is Ubuntu >= 22.04.

First, install Cargo and Rust by following the official instructions. Then, install the eBPF (XDP) requirements:

sudo apt update && sudo apt install clang linux-headers-$(uname -r) libbpf-dev make pkg-config

If you have errors with the <asm/types.h> file, run the following command:

sudo ln -s /usr/include/x86_64-linux-gnu/asm /usr/include/asm

You might also need to install gcc:

sudo apt-get install gcc-multilib

Quick Start

After installing the required dependencies, enter the repo and build the Cargo project:

cargo build -r

Then, run TLSGatekeeper:

sudo target/release/tlsgatekeeper -i <INTERFACE> -g <GUIDELINE_FILEPATH> -o <OUTPUT_FOLDER>

<INTERFACE> is the desired interface
<GUIDELINE_FILEPATH> is one of the default guidelines in etc/guidelines/
<OUTPUT_FOLDER> is the desired output folder for the logs generated by TLSGatekeeper. Make sure the folder exits!

Finally, press Ctrl-C to stop TLSGatekeeper. This will gracefully shut it down and detach the XDP program from the interface. You can check if the XDP was detached by running ip link | grep xdp; if it returns nothing it detached as expected.

A few notes:

• The default mode that XDP is attached is the DRIVE (or native) mode. If your interface does not support it, you can change it to SKB in src/main.rs. However, this mode has low performance.
• Watch out for the MTU of the desired interface, XDP is only alllowed with certain MTU values.
• TLSGatekeeper changes the bpf file every time it is run. This means you need to be careful if you are running multiple TLSGatekeeper instances for the same folder.

Blocking TLS Connections

TLSGatekeeper can send TLS alerts to block connections that do not comply with the desired guidelines. To enable this, run TLSGatekeeper with the -b option:

sudo target/release/tlsgatekeeper -i <INTERFACE> -g <GUIDELINE_FILEPATH> -o <OUTPUT_FOLDER> -b