README.md

ESP32 Firmware Patching Framework

A streamlined framework to assist in patching proprietary ESP32 libraries from Xtensa ELF file or user's code.

Table of Contents

• Requirements
  • Linux/Ubuntu
  • Windows 7/10
• Quick Start Template Project
• Sample Project - Bluetooth BR/EDR Patching
  • Build Patched Firmware
  • Flash Firmware
• Framework - Patching ESP32 from Inside and Outside
  • 1. Patching Proprietary Libraries (Inside/Outside user code)
  • 2. Runtime Patching (Inside user code)
  • 3. ROM Patching (Inside user code)
• Reverse Engineering while Debugging
  • Required Tools
  • GDB & Ghidra Live Synchronization

Requirements

This project was tested to work on the Windows 7/10 or Ubuntu 18.04, but it should work in any system that has Python 3 installed.

Linux/Ubuntu

Run the following to install Python 3 if you don't have it installed on your system yet:

sudo apt-get install python3

Windows 7/10

You can either manually install Python 3 or run the provided batch file requirements.bat on the root folder of this project.

# On Windows 7/10 command prompt
requirements.bat

If Windows store opens when you type python on the command prompt, disable python in "App execution aliases" in settings.

Quick Start Template Project

TODO

Sample Project - Bluetooth BR/EDR Patching

Build Patched Firmware

The provided firmware.py automates the firmware building & patching process. Under the hood, it calls Platformio Framework to:

1. Download Xtensa toolchain, ESP-IDF SDK and openocd debugger. This can be configured on platformio.ini;

2. Compile the main code in src/ folder;

2. Patch the final ELF binary via user provided patch script UserPatch.py, which uses this framework's patching library.

You can build the sample patching project for Bluetooth BR/EDR by running the following:

# On Linux/Ubuntu bash
python3 firmware.py build
# On Windows 7/10 command prompt
python firmware.py build

First time building the firmware will take some time. A successful build output should give you the following output:

Flash Firmware

firmware.py provides a facility to flash the built firmware. If previous step is successful, you can flash the final patched firmware on ESP32 as follows:

# On Linux/Ubuntu bash
./firmware.py flash /dev/ttyUSB0 # Change /dev/ttyUSB0 to match your port name
# On Windows 7/10 command prompt
python firmware.py flash COM4 # Change COM4 to match your port name

Framework - Patching ESP32 from Inside and Outside

TODO

1. Patching Proprietary Libraries (Inside/Outside user code)

TODO

2. Runtime Patching (Inside user code)

TODO

3. ROM Patching (Inside user code)

TODO

Reverse Engineering while Debugging

Required Tools

TODO

GDB & Ghidra Live Synchronization

TODO