🔐 SecureLoader

SecureLoader is a cross-platform tool for uploading 🔒 AES-128 encrypted firmware binaries to embedded devices over a serial link ⚡. It ships with a scriptable CLI (sld) and a Qt6 GUI (sld-gui).

---

🚀 What is it?

SecureLoader is a cross-platform tool that allows flashing embedded devices using encrypted firmware binaries generated by EncryptBIN.

It requires that the target device is already running a compatible bootloader (e.g. SecureBootloader).

SecureLoader handles the host-side flashing process: it reads encrypted .bin files, validates device and firmware compatibility, and streams the firmware over a serial link using a custom XOR-acknowledged protocol 📡.

flowchart LR
    A[Factory / Initial provisioning] --> SB[SecureBootloader flashing] --> D[(Device)]

    A2[EncryptBIN] -->|produces| B([encrypted .bin])
    B -->|input| C[SecureLoader]
    C -->|flashes| D

    classDef tool fill:#3f51b5,stroke:#1a237e,color:#fff,stroke-width:2px
    classDef file fill:#009688,stroke:#004d40,color:#fff
    classDef device fill:#455a64,stroke:#263238,color:#fff

    class A,A2,C tool
    class B file
    class D,SB device

Loading

Related repositories: SecureBootloader · EncryptBIN

Full documentation: https://niwciu.github.io/SecureLoader/

⚠️ Documentation is under active development — expect incomplete sections.

⚙️ How it works

1. 🧾 Firmware validation — reads 48-byte header (version, product ID, CRC32)
2. 🤝 Serial handshake — polls device with GET_VERSION every 500 ms
3. 📦 Streaming — sends firmware page-by-page with ACK confirmation
4. 🔄 Auto reconnect — recovers automatically after connection loss

→ Deep dive: Serial Protocol · Firmware Format · Architecture

---

🔗 Tool Compatibility

The SecureBootloader ↔ SecureLoader pairing is version-locked — a protocol change in SecureLoader v2.0.0 reduced the UART wire header from 48 → 44 bytes:

SecureLoader	SecureBootloader	Compatible
< v2.0.0	v1.0.0	✅
≥ v2.0.0	≥ v1.1	✅
≥ v2.0.0	v1.0.0	❌ device stalls on CMD_START
< v2.0.0	≥ v1.1	❌ header size mismatch

⚠️ Always match the SecureLoader version to the SecureBootloader version deployed on your device. Flash the updated bootloader (≥ v1.1) to the target before deploying SecureLoader v2.0.0 or later.

---

📦 Installation

Python 3.10+ required.

From source

git clone https://github.com/niwciu/SecureLoader.git
cd SecureLoader

pip install -e ".[gui]"  # CLI + GUI
pip install -e .          # CLI only

---

🪟 Windows installer / build scripts

You can install or build SecureLoader directly from the repository using the provided scripts.

First clone the repository:

git clone https://github.com/niwciu/SecureLoader.git
cd SecureLoader

Then go into the install scripts directory:

cd install_scripts

🪟 Windows

Run:

build.bat

🐧 Linux / 🍎 macOS

Run:

./build.sh

This will:

• create a virtual environment 🧪
• install dependencies
• build CLI + GUI application ⚙️
• generate platform-specific output
• optionally create shortcuts / launchers

🧹 Uninstall

To remove a local installation, use the provided uninstall script:

• Windows: uninstall.bat
• Linux/macOS: uninstall.sh

These scripts remove the virtual environment and installed artifacts.

📥 Releases / Downloads / Downloads

👉 https://github.com/niwciu/SecureLoader/releases

Each release may include:

• 🪟 Windows .exe installers and portable builds
• 🐧 Ubuntu/Linux packages (.deb or distribution-specific package)
• 🧰 CLI standalone builds
• 🖥️ GUI builds
• 📄 release notes

⚠️ Some releases may be experimental or in preview state.

---

🧪 Usage

⚡ Important: The usage flow is split into two stages:

1. 🔐 Generate encrypted firmware (external tool)
2. 📡 Connect and flash using SecureLoader (CLI or GUI)

This flow is also reflected in the architecture diagram above.

---

🔐 Step 1 — Generate encrypted firmware

SecureLoader does NOT work with raw binaries. You must first generate an encrypted .bin file using EncryptBIN:

encryptbin input.bin output.bin

This produces:

• AES-128 CBC encrypted firmware 🔐
• 48-byte SecureLoader header 🧾

⚠️ The target device must already be flashed with SecureBootloader before SecureLoader can be used.

---

🧰 CLI usage (single-command flow)

CLI is designed for automation — everything is done in one command:

sld flash --file firmware.bin --port COM3 --baudrate 115200

Typical flow:

1. Select encrypted firmware file
2. Provide serial port
3. Optionally set baud rate
4. Flash starts immediately
5. Tool automatically handles connect → transfer → finish → disconnect

Other useful commands:

sld list-ports
sld info --file firmware.bin
sld info --port COM3

---

📡 Fetching firmware from an HTTP server

SecureLoader can download firmware directly from an HTTP server before flashing — no manual file transfer needed.

The server URL path is built from configurable Product ID sections: named nibble-level slices of the device's 64-bit productId. The default layout matches the EncryptBIN / SecureBootloader convention (license_id and unique_id as path segments), but any split and naming scheme is supported.

# 1. Configure your server URL once (HTTPS is required by default)
sld config set http.base_url https://myserver/update

# 2. Download the latest firmware using the default sections
sld fetch --section license_id=AB --section unique_id=C0FE --output firmware.bin

# 3. Flash as usual
sld flash --file firmware.bin --port /dev/ttyUSB0

To use custom Product ID sections matching your server layout:

# Define a custom split (once, saved to config)
sld config set product_id.sections "product:0:6,serial:6:16"

# Download using the custom section names
sld fetch --section product=AABB --section serial=C0FE0001 --output firmware.bin

If the server requires authentication, set credentials once:

sld config set http.login myuser
sld config set-password          # secure interactive prompt — avoids shell history

⚠️ Plain HTTP (http://) is rejected by default. Pass --allow-insecure to fetch only in isolated lab environments where HTTPS is not available.

The GUI exposes the same feature via the Fetch from server and Get Previous Firmware buttons — both become active once a device is connected. The Settings → Server settings dialog lets you visually design the Product ID section layout and URL path structure.

See the User Guide for HTTP server path requirements and full configuration details.

---

🖥️ GUI usage (interactive flow)

GUI is designed for manual control and visibility:

1. 🚀 Launch application

sld-gui

2. ⚙️ Select:

   • Serial port
   • Baud rate

3. 📂 Load encrypted .bin file

4. 🤝 Click Connect

   • Establishes handshake with device
   • Validates firmware compatibility

5. 📡 Click Update / Flash

   • Streams firmware page-by-page
   • Shows live progress

6. 🔌 Click Disconnect (or automatic after completion)

---

🔄 Connection lifecycle

Both CLI and GUI follow the same internal state machine:

IDLE → CONNECTING → CONNECTED → STARTING → SENDING → CONNECTED (done)

---

🔧 Firmware generation

Uses EncryptBIN to generate:

• AES-128 CBC encrypted firmware 🔐
• 48-byte SecureLoader header 🧾

---

🤝 Contributing

We welcome contributions! Please follow the workflow below:

🧭 Contribution workflow

1. 🍴 Fork the repository on GitHub

2. 📥 Clone your fork

git clone https://github.com/<your-username>/SecureLoader.git
cd SecureLoader

3. 🧪 Install development environment

pip install -e ".[gui,dev]"

4. 🔄 Create a new branch for your changes

git checkout -b feature/my-change

5. 🧷 Make your changes

6. 🧪 Run tests and checks locally

QT_QPA_PLATFORM=offscreen pytest --cov=src/secure_loader --cov-fail-under=70
ruff check src tests
mypy src
black src tests
flake8 src tests
bandit -r src/ -ll -x src/secure_loader/gui/resources
pip-audit --skip-editable

7. 🚀 Push changes to your fork

git push origin feature/my-change

8. ✅ Ensure CI passes on your fork / PR

9. 🔁 Open a Pull Request

• Describe your changes clearly
• Link related issues if applicable

---

📚 Documentation

Full documentation is hosted at: https://niwciu.github.io/SecureLoader/

⚠️ Documentation is currently under active development. Some sections may be incomplete or subject to change.

Page	Contents
User Guide	Installation, CLI reference, GUI walkthrough, configuration
Firmware Format	Binary header layout, field semantics, wire vs. disk format
Serial Protocol	Command set, timing, state machine, bootloader requirements
Architecture	Layer design, module responsibilities, threading model
Contributing	Dev setup, testing, code style, adding sources / languages
Troubleshooting	Common errors and fixes
Security	Vulnerability reporting, scope, threat model

To preview docs locally:

pip install mkdocs mkdocs-material pymdown-extensions
mkdocs serve          # http://127.0.0.1:8000

🔒 Security

To report a vulnerability, see SECURITY.md. Please do not open a public GitHub issue for security problems before contacting privately first.

📄 License

MIT ©

---

---