[docs] Add draft Beken key extraction docs

SUMMARY.md

@@ -14,6 +14,7 @@
 * [](SUMMARY.md)
 * 🍪 Chip family docs & info
 	* [Beken BK72xx](docs/platform/beken-72xx/README.md)
+		* [Finding encryption keys](docs/platform/beken-72xx/keys.md)
 	* [Realtek Ameba - info](docs/platform/realtek-amb/README.md)
 	* [Realtek AmebaZ](docs/platform/realtek-ambz/README.md)
 		* [Debugging](docs/platform/realtek-ambz/debugging.md)

docs/inc/flashing-note.md

@@ -0,0 +1,4 @@
+!!! danger "Read this!"
+	This is probably the most important part of the docs - flashing firmware to the chip.
+
+	**This is why you're here**. Please read this section carefully, and only then start flashing firmware.

docs/inc/uart-cen.md

@@ -1,4 +1,4 @@
-!!! note
+!!! note inline end
 	"CEN" pin is the RESET pin - connecting it to GND will keep the chip in "reset" state. Disconnecting it will allow the chip to start back up.
 
 	If you're having issues with using CEN pin (or if it's not accessible on your device) you can toggle the 3.3V power instead. Removing power will keep it in "reset", and applying it back will start it again.

docs/platform/beken-72xx/README.md

@@ -2,6 +2,9 @@
 
 ## Introduction
 
+!!! note inline end "Also read"
+	- [Finding encryption keys](keys.md) - what to do if LibreTiny doesn't boot because of incorrect flash encryption keys
+
 Beken BK7231 is a family of Wi-Fi and BLE microcontrollers, of which most popular are BK7231N and BK7231T.
 
 Features:
@@ -28,8 +31,14 @@ Resources:
 	include-markdown "../../inc/find-board.md"
 %}
 
+---
+
 ## Flashing
 
+{%
+	include-markdown "../../inc/flashing-note.md"
+%}
+
 BK7231 has two UART ports - UART2 (sometimes called LOG_UART) and UART1. The UART1 port is used for flashing (and external components, such as TuyaMCU) and has no text output. The UART2 port is used for log viewing only.
 
 You need to find which pins correspond to UART1 TX and RX. If your board is supported, you'll find the pinout on its documentation page. Otherwise (and for generic boards), you'll have to find the pinout online.
@@ -53,12 +62,12 @@ GND | GND
 	include-markdown "../../inc/uart-power.md"
 %}
 
-The download mode is entered when the chip communicates with the flasher program. Hence, the first step is running the flasher program (described below). While the program is trying to establish communication, **the chip has to be rebooted**. In order to do that, you need to bridge CEN pin to GND with a wire.
-
 {%
 	include-markdown "../../inc/uart-cen.md"
 %}
 
+The download mode is entered when the chip communicates with the flasher program. Hence, the first step is running the flasher program (described below). While the program is trying to establish communication, **the chip has to be rebooted**. In order to do that, you need to bridge CEN pin to GND with a wire.
+
 Keep in mind that BK7231T (not N) will exit the download mode when it can't communicate with the flasher (or when the flasher finishes its work). It's not possible to forcefully enter download mode without it.
 
 After linking with the chip, the flasher program will begin writing (or reading) the firmware automatically. If that doesn't happen, try resetting the chip again until it works.
@@ -79,7 +88,9 @@ The recommended tool to flash (or dump firmware) is `ltchiptool`.
 
 	`ltchiptool`'s Beken flashing program is based on [bk7231tools](https://github.com/tuya-cloudcutter/bk7231tools). Refer to the guide for information how to use it, but keep in mind that using the ltchiptool GUI is probably just easier.
 
-### Auto-download-reboot
+---
+
+## Auto-download-reboot
 
 {%
 	include-markdown "../../inc/uart-adr.md"

docs/platform/beken-72xx/keys.md

@@ -0,0 +1,48 @@
+# Finding encryption keys
+
+## Introduction
+
+!!! tip inline end
+	Before proceeding with this method, try using [ltchiptool](../../flashing/tools/ltchiptool.md)'s `Get chip info`
+	function. It will read eFuse, which may reveal the raw encryption key. If you see all `00000000`s, then the eFuse
+	is readout-protected and the key cannot be extracted in this simple way.
+
+3-rd party firmware for Beken chips must be compiled with a flash encryption key matching the one programmed into
+the chip. Incorrect keys will make the firmware unable to run.
+
+The [`bk72xx-bootloader-dump`](https://github.com/libretiny-eu/bk72xx-bootloader-dump) firmware might make it easier
+to find the encryption key of BK7231N/BK7231T chips.
+
+The key is made of four 32-bit integers; the default key is usually `510fb093 a3cbeadc 5993a17e c7adeb03`
+(used by Beken and Tuya on most devices), but devices with different keys have been recently discovered
+(likely from other manufacturers).
+
+If your device doesn't use the default keys (i.e. 3-rd party firmware doesn't boot up, or it hangs on bootloader logs),
+you can try using this firmware file to extract the keys from the bootloader.
+
+## Why this works (and when it doesn't)
+
+The bootloader has its own copy of the keys. It uses that to encrypt firmware on-the-fly when applying OTA updates.
+
+Files downloaded during an OTA update are *not* encrypted using the main encryption keys, so the bootloader
+must encrypt them before flashing to the app partition. **This method works by flashing firmware directly to the**
+**OTA partition**. It is then unpacked and encrypted properly by the bootloader.
+
+However, OTA update packages *are* encrypted using AES - for this method to work, the AES key must be known in advance.
+
+Most of the time, a simple `0123456789ABCDEF` key is used for OTA AES. We have seen manufacturers using different
+keys - this method will not work in that case.
+
+Additionally, OTA packages **don't have to** be encrypted - some bootloaders allow that, some don't. Using an
+unencrypted package is worth trying if your device uses a non-standard OTA AES key.
+
+## Prerequisites
+
+1. A working computer with a working UART flashing setup. The preferred flashing tool is
+[ltchiptool](../../flashing/tools/ltchiptool.md). You should have at least some prior experience with dumping
+or flashing firmware.
+2. **A full factory firmware dump** of the device you're working on. This is mostly in case something goes wrong,
+but may also be necessary to read OTA partition offsets from.
+3. A serial terminal (such as the [`ltchiptool-terminal`](https://github.com/libretiny-eu/ltchiptool-terminal) plugin).
+
+## To be continued

docs/platform/realtek-ambz/README.md

@@ -27,6 +27,8 @@ Resources:
 	include-markdown "../../inc/find-board.md"
 %}
 
+---
+
 ## Flashing
 
 Realtek RTL8710B has two UART ports - UART2 (sometimes called LOG_UART) and UART0. The port used for flashing and viewing logs is UART2.
@@ -54,17 +56,17 @@ GND | GND
 
 In order to flash the chip, you need to enable **download mode**. This is done by resetting the chip while pulling down the TX2 pin.
 
+{%
+	include-markdown "../../inc/uart-cen.md"
+%}
+
 Do this, in order:
 
 - connect CEN to GND
 - connect TX2 to GND
 - release CEN from GND
 - release TX2 from GND
 
-{%
-	include-markdown "../../inc/uart-cen.md"
-%}
-
 To find out whether download mode is enabled, open a serial terminal (such as PuTTY) on your PC. You should see a few characters printed to the serial console every second (usually some kind of grey blocks, or other non-letter characters).
 
 Note that you will not see any characters before you release TX2 from GND.
@@ -86,7 +88,9 @@ The recommended tool to flash (or dump firmware) is `ltchiptool`.
 !!! tip
 	Because the UART uploading code is programmed in the ROM of the chip, it can't be software-bricked, even if you damage the bootloader.
 
-### Auto-download-reboot
+---
+
+## Auto-download-reboot
 
 {%
 	include-markdown "../../inc/uart-adr.md"

mkdocs.yml

@@ -43,6 +43,7 @@ plugins:
         "link/config-serial.md": "docs/dev/config.md#serial-output"
         "link/flashing-beken-72xx.md": "docs/platform/beken-72xx/README.md#flashing"
         "link/flashing-realtek-ambz.md": "docs/platform/realtek-ambz/README.md#flashing"
+        "link/bk72xx-keys.md": "docs/platform/beken-72xx/keys.md"
         "link/kickstart.md": "https://github.com/libretiny-eu/esphome-kickstart/releases/latest"
   - section-index
   - include-markdown