-"tools/espota.py"

-"tools/gen_esp32part.py"

-"tools/gen_insights_package.py"

-"tools/bin_signing.py"

permissions:

contents:write

-name:List all changed files

shell:bash

-name:Install dependencies

run:|

-name:Build with PyInstaller

shell:bash

set(ARDUINO_LIBRARY_Update_SRCS

libraries/Update/src/Updater.cpp

libraries/Update/src/HttpsOTAUpdate.cpp)

libraries/Update/src/HttpsOTAUpdate.cpp

libraries/Update/src/Updater_Signing.cpp)

set(ARDUINO_LIBRARY_USB_SRCS

libraries/USB/src/USBHID.cpp

This example demonstrates how to perform secure OTA updates with cryptographic signature verification using the ArduinoOTA library.

**SignedOTA** adds an extra layer of security to Arduino OTA updates by requiring all firmware to be cryptographically signed with your private key. This protects against:

- ✅ Unauthorized firmware updates

- ✅ Man-in-the-middle attacks

- ✅ Compromised networks

- ✅ Firmware tampering

- ✅ Supply chain attacks

Even if an attacker gains access to your network, they**cannot** install unsigned firmware on your devices.

-**RSA & ECDSA Support**: RSA-2048/3072/4096 and ECDSA-P256/P384

-**Multiple Hash Algorithms**: SHA-256, SHA-384, SHA-512

-**Arduino IDE Compatible**: Works with standard Arduino OTA workflow

-**Optional Password Protection**: Add password authentication in addition to signature verification

-**Easy Integration**: Just a few lines of code

-**ESP32 Arduino Core 3.3.0+**

-**Python 3.6+** with`cryptography` library

-**OTA-capable partition scheme** (e.g., "Minimal SPIFFS (1.9MB APP with OTA)")

cd<ARDUINO_ROOT>/tools

pip install cryptography

python bin_signing.py --generate-key rsa-2048 --out private_key.pem

python bin_signing.py --extract-pubkey private_key.pem --out public_key.pem

**⚠️ IMPORTANT: Keep`private_key.pem` secure! Anyone with this key can sign firmware for your devices.**

1. Copy`public_key.h` (generated in step 1) to this sketch directory

2. Open`SignedOTA.ino` in Arduino IDE

3. Configure WiFi credentials:

constchar *ssid ="YourWiFiSSID";

constchar *password ="YourWiFiPassword";

4. Select appropriate partition scheme:

-**Tools → Partition Scheme → "Minimal SPIFFS (1.9MB APP with OTA)"**

1. Connect your ESP32 via USB

2. Upload the sketch normally

3. Open Serial Monitor (115200 baud)

4. Note the device IP address

**Option A: Using Arduino IDE**

cd<ARDUINO_ROOT>/tools

python bin_signing.py \

--bin /path/to/SignedOTA.ino.bin \

--key private_key.pem \

--out firmware_signed.bin

**Option B: Using arduino-cli**

arduino-cli compile --fqbn esp32:esp32:esp32 --export-binaries SignedOTA

cd<ARDUINO_ROOT>/tools

python bin_signing.py \

--bin build/esp32.esp32.esp32/SignedOTA.ino.bin \

--key private_key.pem \

--out firmware_signed.bin

Upload the signed firmware using`espota.py`:

python<ARDUINO_ROOT>/tools/espota.py -i<device-ip> -f firmware_signed.bin

The device will automatically:

1. Receive the signed firmware (firmware + signature)

2. Hash only the firmware portion

3. Verify the signature

4. Install if valid, reject if invalid

**Note**: You can also use the Update library's`Signed_OTA_Update` example for HTTP-based OTA updates.

Choose one in`SignedOTA.ino`:

#defineUSE_SHA256 // Default, fastest

**Must match** the`--hash` parameter when signing:

python bin_signing.py --bin firmware.bin --key private.pem --out signed.bin --hash sha256

Choose one in`SignedOTA.ino`:

#defineUSE_RSA // For RSA keys

Add password authentication**in addition to** signature verification:

constchar *ota_password ="yourpassword";// Set password

**Cause**: Signature verification setup failed, or partition scheme issue

**Solutions**:

1. Check partition scheme (use "Minimal SPIFFS (1.9MB APP with OTA)")

2. Verify`public_key.h` is in the sketch directory

3. Check hash and signature algorithm match your key type

**Cause**: Signature verification failed

**Solutions**:

1. Ensure firmware was signed with the**correct private key**

2. Verify hash algorithm matches (SHA-256, SHA-384, SHA-512)

3. Check firmware wasn't corrupted during signing/transfer

4. Confirm you signed the**correct**`.bin` file

**Cause**: Network timeout or connection issue

**Solutions**:

1. Check Wi-Fi signal strength

2. Ensure device is reachable on the network

3. Try increasing timeout:`ArduinoOTA.setTimeout(5000)`

**Issue**: OTA upload fails or times out

**Solutions**:

1. Verify device is on the same network

2. Check firewall settings aren't blocking port 3232

3. Ensure Wi-Fi signal strength is adequate

4. If using password protection, ensure the password is correct

5. Try:`python <ARDUINO_ROOT>/tools/espota.py -i <device-ip> -f firmware_signed.bin -d`

✅**Keep private key secure**: Never commit to git, store encrypted

✅**Use strong keys**: RSA-2048+ or ECDSA-P256+

✅**Use HTTPS when possible**: For additional transport security

✅**Add password authentication**: Extra layer of protection

✅**Rotate keys periodically**: Generate new keys every 1-2 years

- ✅ Unsigned firmware installation

- ✅ Firmware signed with wrong key

- ✅ Tampered/corrupted firmware

- ✅ Network-based attacks (when combined with password)

- ❌ Physical access (USB flashing still works)

- ❌ Downgrade attacks (no version checking by default)

- ❌ Replay attacks (no timestamp/nonce by default)

- ❌ Key compromise (if private key is stolen)

For production deployments, consider:

1.**Add version checking** to prevent downgrades

2.**Add timestamp validation** to prevent replay attacks

3.**Use secure boot** for additional protection

4.**Store keys in HSM** or secure key management system

5.**Implement key rotation** mechanism

ECDSA keys are smaller and faster:

python bin_signing.py --generate-key ecdsa-p256 --out private_key.pem

python bin_signing.py --extract-pubkey private_key.pem --out public_key.pem

In`SignedOTA.ino`:

#defineUSE_SHA256

#defineUSE_ECDSA // Instead of USE_RSA

In `SignedOTA.ino`:

```cpp

#defineUSE_SHA384 // Instead of USE_SHA256

#define USE_RSA

## Support

For issuesand questions:

- Update Library README: `libraries/Update/README.md`

- ESP32 Arduino Core: https://github.com/espressif/arduino-esp32

- Forum: https://github.com/espressif/arduino-esp32/discussions

## License

This library is part of the Arduino-ESP32 projectand is licensed under the Apache License2.0.