= Ourosboros Flash Reader :revealjsdir: ./reveal.js-5.2.1/ Patrick Schönberger 16.07.2025 == Structure - Problem - Solution - Implementation == Problem == Solution == Implementation structure: start with a problem and reproduce the work leading to the working solution access smart home hw on crime scenes many shelly devices are based on esp32/esp8266 they dont contain any usable data but contain identifiable user data this can be used to inquire about the user account so we need to extract the content of the esp's flash memory we then also need to extract filesystems from the memory do it read-only, verifiably existing solutions (esptool, mos) can also write and erase memory they are also complex, making understanding and changing the code time consuming what about writing a custom extraction tool? what is the bare minimum needed to talk to the esp? - two modes: bootmode and runmode - decided by GPIO0 at start - the esp as well as the shelly devices expose uart pins (tx/rx) - in runmode they output logging information - in bootmode they listen to a custom serial protocol so we need a serial connection and the ability to enter boot mode! what can the serial protocol do? - sync - write ram/flash/registers - configuration etc. - on the esp32 it can read flash, but not on esp8266, esp32c3, esp32c6 how do other tools read flash? - we cant directly read flash, but we can write ram - write a program, load it into ram, run it and then talk to it instead - flash loader/stub - esptool uses two different variants, c based and rust based - the c based one is older and getting replaced, but it is also dramatically simpler and also supports the esp8266 - so we use the c based one and customize it (remove write and erase flash commands) technically this means we do have write access until the flash loader is activated the extraction tool is also small and runs a fixed number of commands -> as sure as we can be how does the serial protocol work? - data is encoded using SLIP frames - the host sends a request and the target (esp) sends a response - steps to read flash: - sync - identify chip - read mac - (change baud) - upload stub - read flash modifying the flash loader - stub consists of 6 .c files: - miniz.c // compression - slip.c // slip - stub_commands.c // handle commands - stub_flasher.c // main program - stub_io.c // serial communication - stub_write_flash.c // write flash - so we remove stub_write_flash.c and modify stub_commands.c - additionally simplify the makefile compiling and uploading the flash loader - download toolchains - compile the stub using specific toolchains - this gives us an elf file - use a python script to extract the .text and .data sections from the elf - generate a header file and write the raw bytes to a `const unsigned char[]` - this header gets compiled with the extraction tool (host) - at runtime, after the chip is identified, upload .text and .data using MEM_ ram commands - addresses for the sections and for the entry point are in elf file and get written to header alongside the elf sections and how do we make the esp enter bootmode? - wire two gpio pins to RST and GPIO0 - pull both low - RST low turns the esp off - GPIO0 has to be low when it is turned back on - pull RST high to turn it on - pull GPIO0 high after the esp has started overview: - bootmode/serial - serial protocol - flash loader differences between esp versions - identification: - ESP32-C3 and later use GET_SECURITY_INFO which contains a chip_id - previous models have a register with a magic value identifying the chip - mac address: - different registers - esp8266 mac has to be calculated - different flash loader versions - esp8266 has no data section different hosts: - linux (usb) - rpi (gpio) - esp (gpio) extracting the file system - esp8266 - esp32 interesting files - wifi credentials - certificates - jwt token DEMO! == cloc ```sh $ cloc esp-flasher-stub/ 38 text files. 34 unique files. 5 files ignored. github.com/AlDanial/cloc v 2.04 T=0.02 s (2259.9 files/s, 199599.0 lines/s) ----------------------------------------------------------- Language files blank comment code ----------------------------------------------------------- Rust 12 327 78 1863 Logos 14 32 0 249 YAML 3 34 12 214 Markdown 1 34 0 89 TOML 4 8 2 61 ----------------------------------------------------------- SUM: 34 435 92 2476 ----------------------------------------------------------- $ cloc esp-hal 742 text files. 718 unique files. 35 files ignored. github.com/AlDanial/cloc v 2.04 T=0.36 s (1978.1 files/s, 522278.6 lines/s) ----------------------------------------------------------- Language files blank comment code ----------------------------------------------------------- Rust 492 18739 26120 115809 Linker Script 51 499 1404 11315 Markdown 66 2014 12 5262 TOML 43 505 412 4481 Logos 44 229 15 1105 YAML 13 151 67 1054 Jinja Template 3 52 0 255 JSON 2 0 0 48 CSV 3 0 0 21 SVG 1 0 0 4 ----------------------------------------------------------- SUM: 718 22189 28030 139354 ----------------------------------------------------------- $ cloc esptool-legacy-flasher-stub/ 63 text files. 60 unique files. 4 files ignored. github.com/AlDanial/cloc v 2.04 T=0.06 s (952.9 files/s, 535446.8 lines/s) ----------------------------------------------------------- Language files blank comment code ----------------------------------------------------------- Linker Script 32 787 1188 18751 C 6 1284 636 7689 C/C++ Header 8 463 557 1687 make 1 36 33 130 YAML 4 19 0 114 Python 2 25 21 80 Markdown 3 58 0 76 Bourne Shell 2 9 8 23 TOML 1 1 0 20 Jinja Template 1 4 2 14 ----------------------------------------------------------- SUM: 60 2686 2445 28584 ----------------------------------------------------------- ```