Added readme

AutoKeyboxDecoder/Readme.md

@@ -0,0 +1,223 @@
+# 🔐 SuperUserek Auto AES Decrypt Tool
+
+A Python tool that attempts to decrypt **LG firmware / keybox / encrypted blobs** by automatically testing known AES keys and AES modes.
+
+The script downloads multiple public key lists and tries them using several AES modes and IV strategies.
+
+If a valid payload is found, the decrypted payload is extracted and saved.
+
+---
+
+# ✨ Features
+
+* 🔑 Automatically downloads known AES keys from multiple sources
+* 🧠 Supports **AES-128 / AES-192 / AES-256**
+* 🔍 Tests multiple AES modes automatically
+* ⚡ Fast key testing
+* 🧩 Supports **custom user-provided AES keys**
+* 📦 Extracts valid payload automatically
+* 📁 Supports custom output directories
+
+---
+
+# 📦 Key Sources
+
+By default the script downloads keys from:
+
+### 1️⃣ openlgtv AES keys
+
+https://raw.githubusercontent.com/openlgtv/epk2extract/refs/heads/master/keys/AES.key
+
+### 2️⃣ DRMLAB's KnownKeys ( please contribute and add more working keys to extract keyboxes )
+
+https://git.drmlab.io/SuperUserek/MyDRMTools/AutoKeyboxDecoder/KnownKeys.txt
+
+These lists contain AES keys used in various LG firmware and DRM systems.
+
+---
+
+# ⚙️ Requirements
+
+Python **3.8+**
+
+Install dependencies:
+
+```bash
+pip install requests pycryptodome
+```
+
+---
+
+# 🚀 Basic Usage
+
+Try all known keys from both sources:
+
+```bash
+python3 autokeybox_decoder.py keybox_file.dat
+```
+
+The script will:
+
+1. Download key lists
+2. Parse AES keys
+3. Try AES modes automatically
+4. Save the decrypted payload if successful
+
+---
+
+# 🔑 Custom AES Key
+
+Try a custom AES key **along with known keys**:
+
+```bash
+python3 autokeybox_decoder.py keybox_file.dat --key 00112233445566778899AABBCCDDEEFF
+```
+
+Supported key sizes:
+
+| AES Type | Hex Length |
+| -------- | ---------- |
+| AES-128  | 32         |
+| AES-192  | 48         |
+| AES-256  | 64         |
+
+---
+
+# 🔒 Only Use Custom Key
+
+Skip downloading key lists:
+
+```bash
+python3 autokeybox_decoder.py keybox_file.dat \
+--key 00112233445566778899AABBCCDDEEFF \
+--only-custom
+```
+
+---
+
+# 📂 Specify Output Directory
+
+```bash
+python3 autokeybox_decoder.py keybox_file.dat --outdir ./output
+```
+
+Example output:
+
+```
+output/file_decrypted_CBC_IV_PREFIX16_0011223344556677.dat
+```
+
+---
+
+# 🧪 Save All Matches
+
+By default the script stops after the **first successful decrypt**.
+
+To save **all possible matches**:
+
+```bash
+python3 autokeybox_decoder.py keybox_file.dat --all-matches
+```
+
+---
+
+# 🌐 Add Additional Key Lists
+
+You can add extra key sources:
+
+```bash
+python3 autokeybox_decoder.py keybox_file.dat \
+--keys-url https://example.com/keys.txt
+```
+
+Multiple lists are supported:
+
+```bash
+python3 autokeybox_decoder.py keybox_file.dat \
+--keys-url https://example.com/keys1.txt \
+--keys-url https://example.com/keys2.txt
+```
+
+---
+
+# 🧰 Full Example
+
+Use known keys + custom key + save all matches:
+
+```bash
+python3 autokeybox_decoder.py keybox.dat \
+--key BC1197CA30AA0FC84F7FE62E09FD3D9F \
+--all-matches \
+--outdir decrypted
+```
+
+---
+
+# 🔐 AES Modes Tested
+
+The script automatically tries:
+
+* AES **ECB**
+* AES **CBC**
+* AES **CFB**
+* AES **OFB**
+* AES **CTR**
+
+### IV strategies tested
+
+* zero IV
+* first 16 bytes of file
+* counter derived from prefix
+
+---
+
+# 🧠 Success Detection
+
+A decryption is considered valid if the plaintext contains:
+
+```
+INNER_MSTAR
+```
+
+---
+
+# 📄 Output Format
+
+Successful decryptions are saved as:
+
+```
+<original>_decrypted_<mode>_<keyprefix>.dat
+```
+
+Example:
+
+```
+firmware_decrypted_CBC_IV_PREFIX16_1F1E1D1C1B1A1918.dat
+```
+
+---
+
+# 🖥 Example Output
+
+```
+[*] Keys ready:
+    AES-128: 72
+    AES-192: 0
+    AES-256: 18
+    Total:   90
+
+[+] MATCH: key=1F1E1D1C1B1A19180706050403020100 mode=CBC(IV_PREFIX16)
+    Saved: firmware_decrypted_CBC_IV_PREFIX16_1F1E1D1C1B1A1918.dat
+```
+
+---
+
+# ⚠️ Disclaimer
+
+This tool is intended for:
+
+* firmware research
+* security analysis
+* reverse engineering
+
+Use responsibly and only on data you are authorized to analyze.