## OVERVIEW:
	This is the implementation corresponding to the NDSS 2025 paper "Rediscovering Method Confusion in Proposed Security Fixes for Bluetooth"[4].
	All modifications to existing codebasis were performed by Maximilian von Tschirschnitz.

	This project contains three seperate Bluetooth stack implementations.
	1. MBTstack: Standard Bluetooth stack extended with debug hooks for debugging
	2  PatchedMBTstack: MBTstack patched according to the works of [1], PE replaced with PPE and NC with PNC
	3. XMBTstack: MBTstack patched according to the paper proposal, PE replaced with XPE and NC with XNC

	For each of these stacks there are multiple device implementations for Bluetooth device Responder and Initiator available (we call them victims) in:
	unpatched_victims
	patched_victims
	x_victims

	Further this project contains two MitM implementations that are available after building in the root folder
	pnc_mitm_pe.bin
	pnc_mitm_ppe.bin


## BUILDING:
	This project requires:
		pkg-config
		make
		libsodium-dev
		libusb

	make sure to install these requirements ahead of building using your local packetmanager.

	You can build all the device implementations by changing to the respective directory and running "make"
	To build the MitM implementations you may run "make" in the root directory.

## RUNNING
	BTstack and our adaptations support a variety of Bluetooth hardware through HCI over USB (USB Bluetooth Dongles). For a complete list of tested hardware check source [2] and look out for HCI Transport: USB.
	To run our device implementations with supported hardware you must find the usb bus and device id.

	IMPORTANT NOTE: In the following we run all examples as root.
	This is necessary to reach the usb device in every case.
	To AVOID running the examples as root please consult to set the udev rules (or whatever is relevant on your OS) appropriately.

	Example output of "lsusb": 
	"Bus 001 Device 010: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)"
	=> Bus would be 1 and Device ID 10.

	### Victim Device Example
		A Bluetooth Pairing always consists of the Initiator (the one initiating the Pairing) and the Responder.

		To run any Responder example you can use the following syntax
		sudo ./<responder_example_name> <USB_BUS>:<USB_ID> 

		This will initialize the stack and the hardware and output the Bluetooth address of the ready Responder:
		"RESP(GEN): BThack up and running on 01:AA:BB:CC:DD:EE."

		To run any Initiator example and start pairing with a running Responder:
		sudo ./<initiator_example_name> <USB_BUS>:<USB_ID> <TARGET_RESPONDER_MAC_ADDRESS>

		Make sure to not accidentally confuse the Responder and Initiator of different stacks.

	### MitM Example
		To run the MitM example you must provide two usb devices, one for each side of the MitM application
		sudo ./<mitm_example_name> <USB_INITIATOR_BUS>:<USB_INITIATOR_ID> <USB_RESPONDER_BUS>:<USB_RESPONDER_ID> <TARGET_RESPONDER_MAC_ADDRESS> 

## Reproduce Attacks
	To reproduce the attack PNC vs. two times PE
	we recommend the following procedure:
	1. Launch an *unpatched* victim responder (for the PE side)
	2. Launch the pnc_mitm_pe.bin with target address set to the already running responder
	3. Launch the *patched* victim Initiator with target address set to the running MitM Responder
	4. Interact with victims according to user model
	5. Profit $$$

	To reproduce the attack PNC vs. PPE
	we recommend the following procedure:
	1. Launch an *patched* victim responder (for the PE side)
	2. Launch the pnc_mitm_ppe.bin with target address set to the already running responder
	3. Launch the *patched* victim Initiator with target address set to the running MitM Responder
	4. Interact with victims according to user model
	5. Profit $$$

	Note: Consider the Point Jamming & Spoofing if you are interested in a even more realistic attack setup


## CONFIGURATION
	You can change parameters of the Bluetooth devices in the btstack_config.h file.
	Most importantly you may adjust the Timing window for XPE and XNC by modifying X_PATCH_TIMEWINDOW_T_SECONDS


## SPOOFING & JAMMING
	If you are interested in the process of leading the victim Initiator to communicate with your MitM Responder you
	might want to check out the following project.
	https://github.com/maxdos64/BThack
	Here the authors implemented an end2end deception framework that achieves the sought after goal.


## PERFORMANCE MEASUREMENT
	To compare the performance of the various implementations we developed a client server based setup
	that allows to automate the pairing process and simultaniously collect benchmarking data.
	The client and server can be executed on the same or on seperate devices.
	In any case the applications are designed to communicate over tcp sockets, so a free port must be choosen and the client must be provided with the servers IP address.
	When initialized, the server executes the respective Responder application on the specified hardware and waits for a connection.
	As soon as the client becomes active and establishes a connection it uses the specified Initiator application to connect to the server device.
	Pairing is executed, and pairing values (like passkeys and comparison values) are passed over TCP between the applications.
	There are two benchmarking options: micro and macro benchmarks.
	The macro benchmark will measure the instruction and cycle count as well as memory usage of the whole application while the micro
	benchmark only measures the instruction and cycle count of the cryptographic operations.
	Furthermore every execution of BTstack generates a pcap file in the /tmp directory of the system.
	The eval folder contains tooling to evaluate the amounted network payload sizes of a pairing. Sample pcap files
	can be found in the network_measurements folder.

	Usage:
	To profile using the micro benchmark, enter the respective directory and run: make clean && MEASURE=1 make.
	To profile using the macro benchmark, enter the respective directory and run: make clean &&QUIT_ON_SUCCESS=1 make.
	Open two terminals in the root directory, one for the Initiator and one for Responder device.
	Let us assume we are profiling a sample in `unpatched_victims',  `responder.bin' and `pe_initiator.bin'.
	We always begin by conducting one regular pairing between the Initiator and Responder to test functionality and gather the Bluetooth address of the Responder.

	Subsequently, a benchmark (e.g., in this case macro) can be run as follows.
	On the Responder side (from the root directory):
		sudo ./measure-macro.py -s <LISTENING_PORT> ./unpatched_victims/responder.bin <USB_BUS>:<USB_ID>
	And on the Initiator side (root directory): 
		sudo ./measure-macro.py -c <RESPONDER_DEVICE_IP> <RESPONDER_DEVICE_PORT> ./unpatched_victims/pe_initiator.bin <USB_BUS>:<USB_ID> <TARGET_RESPONDER_MAC_ADDRESS>

	To perform a micro benchmark, you may compile the samples accordingly (MEASURE=1) and use the same syntax and procedure, only replacing `measure-macro.py' with `measure.py'.


## TROUBLESHOOTING
	1. Check that you are not using one of the usb devices in two different programs at the same time.
	2. Check that you are using examples of the same stack together (except of course you intentionaly plan to confuse them) ;)
	3. With some Bluetooth USB Dongles (also internal ones) it is sometimes necessary to reset them through power cycling (plug out/plug in)


## IMPLEMENTATION AND CODE CHANGES
	We selected BTstack due to it's modular structure and modfiability.
	We encourage further development and scruteny of our code changes.
	For that, we refer to the src/ble/sm.c file of the XMBTstack, PatchedBTstack directories as these contain the relevant changes
	to the Bluetooth state machine which introduce the functionality of [1] and our paper respectively.
	For further details of the actual implementation changes we refer to the implementation sections in our publication on NDSS 2025 [4].




[1] https://www.usenix.org/system/files/usenixsecurity23-shi-min.pdf
[2] https://github.com/bluekitchen/btstack#evaluation-platforms
[3] https://github.com/bluekitchen/btstack/blob/master/port/libusb/README.md
[4] https://dx.doi.org/10.14722/ndss.2025.240310