Skip to content

Verify TLS for the "Update Firmware (GitHub)" download (currently unauthenticated) #9

Closed

Description

@daniel-frenkel

Priority: higher than #8. It affects every unit in the field that uses "Update Firmware (GitHub)". That's every product on valar-core.

Problem

valar-core sets http_request: verify_ssl: false. The "Update Firmware (GitHub)" button downloads <asset>.ota.bin.md5, then <asset>.ota.bin, and checks one against the other. Both come over HTTPS without verifying the server's certificate, and the checksum comes from the same place as the file. So the device can't tell whether it is really talking to GitHub, and the md5 only catches corruption, not substitution. Once someone presses the button, the integrity of what gets installed rests entirely on the network path between the unit and GitHub.

What's already on every unit (measured, ESPHome 2026.5.3 / ESP-IDF 5.5.4)

  • CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=y with the CMN (common CAs) bundle is already compiled into the firmware (x509_crt_bundle, 17,924 B). Verification is merely switched off (CONFIG_ESP_TLS_INSECURE=y, CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY=y).
  • The download crosses two CA families:
    • github.com (asset URL, 2× 302): Sectigo DV E36 → Sectigo Root E46 → USERTrust ECC
    • release-assets.githubusercontent.com (the file): Let's Encrypt YR1 → ISRG Root YR, cross-signed by ISRG Root X1

Fix options: flash cost measured on both boards

Baseline v2.12.1: VAL3000 1,214,248 B (66.2 %), VAL3100 1,315,220 B (71.7 %) of a 1,835,008 B app slot. Static RAM in brackets.

Option VAL3000 VAL3100 Notes
A. verify_ssl: true, existing CMN bundle +144 B (66.2 %) +144 B (71.7 %) [+0 RAM]. Hardware-proven: a full GitHub update over verified TLS on a VAL3000. Both chains validated (incl. LE's Root YR via the X1 cross-sign); md5 fetched, 1.1 MB image in 20 s, rebooted into the new image.
B. verify_ssl: true + full bundle (esp32: framework: advanced: use_full_certificate_bundle: true) +51,208 B (69.0 %) +51,208 B (74.5 %) [+0 RAM]. More CA headroom if GitHub's or its CDN's CA ever falls outside CMN.
C. Pinned CA(s) via ca_certificate_path ≈ PEM size (a few KB); up to −18 KB if the bundle is also dropped same Not recommended. Must pin both families above, and breaks the update path as soon as either rotates. LE is mid-rotation to its new YR hierarchy right now. A broken pin strands units until they're re-flashed over USB or the web flasher.
D. Signed images (ESP-IDF signed-app verification) small small Authenticates the image itself, whatever the transport. Needs a Valar-held signing key, which conflicts with the owner's constraint on #8 ("Valar manages no keys, ever"). Listed for completeness; excluded unless the owner rules otherwise.
E. SHA-256 instead of MD5, or a checksum from a second URL ~0 ~0 Doesn't authenticate anything on its own while the transport is unverified. Only worth doing together with A/B.

Caveats

  • No expiry check: CONFIG_MBEDTLS_HAVE_TIME_DATE is off, so chains are verified but certificate validity dates aren't. That's normal for devices without a trusted clock at boot.
  • The bundle ages with the firmware. If GitHub or its CDN moved to a CA outside the bundle, units couldn't self-update until re-flashed. Regular releases refresh the bundle with ESP-IDF, and B widens the margin. No insecure fallback: falling back to unverified downloads would undo the fix.
  • Migration: units in the field take the fix through one last unverified update. Every update after that is verified.

Recommendation

A now: one line in valar-core, +144 B, already proven on hardware. Then consider B if flash allows; VAL3100 would go to ~74.5 %, and #8's add-on (~79 KB) also has to fit.

Testing before release

  • Positive, VAL3000: full GitHub update over verified TLS (above)
  • Positive, VAL3100 (C6), and Glasscalibur
  • Negative: a test build pointed at a host with an untrusted certificate must refuse the download (proves verification is enforced, not just compiled)
  • Heap headroom during the verified handshake on each board (watch for allocation failures in the log)
  • Regression gate per product, then bump the valar-core tag in each product

🤖 Generated with Claude Code

Activity

  1. daniel-frenkel commented on Nov 17, 2026

    @daniel-frenkel
    MemberAuthor

    Option A approved and merged in #10, tagged valar-core v0.3.1: verified TLS for the GitHub update (+144 B), plus a "Firmware Update" status on the page showing progress, or Failed: <why>. Firmware unchanged.

    Hardware results (Ropener VAL3000 on v0.3.1):

    • Success: a verified update through both certificate chains, with the status shown on the page.
    • Failure: a build that can't verify GitHub's certificate refused the update at the TLS handshake (certificate verification failed). It downloaded nothing, kept running its current firmware, didn't restart, and showed the reason on the page.

    How products get the fix: each product that uses valar-core picks it up at its next release, by bumping its valar-core ref to v0.3.1 or later, each with its own update test on its hardware (verified update succeeds; failure case refused).

    Until a product ships the bump, its units in the field keep the old, unverified download. The first update to a fixed release still goes over the old path; every update after that is verified.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions