Skip to content

Releases: nilava/immurok-esp32

Release list

v1.0.0 — first public release

v1.0.0 — first public release Latest
Latest

Choose a tag to compare

View all tags
@nilava nilava released this 31 Aug 09:03
v1.0.0
74beff8

First public release.

Firmware for a Seeed XIAO ESP32-S3 + ZW101 fingerprint sensor that speaks the
immurok BLE protocol, so immurok's companion apps drive it
unmodified. Not affiliated with immurok — see the README.

Flash it

No ESP-IDF needed. Python and esptool only:

pip install esptool
esptool.py --chip esp32s3 write_flash 0x0 immurok-esp32-v1.0.0-merged.bin

The merged image contains bootloader + partition table + app, so it goes at offset 0x0
as a single file. Add -p PORT if the board isn't found. If flashing fails, hold BOOT,
tap RESET, release BOOT, retry.

Verify first: shasum -a 256 -c SHA256SUMS

A prebuilt binary for a security device is a trust decision. The checksums prove the
download matches what was uploaded — not what went into it. Build from source if that
matters to you; ESP-IDF v5.3.2, idf.py set-target esp32s3 && idf.py flash.

What works

Pairing (ECDH P-256 + HKDF), fingerprint enrolment and matching, screen unlock, sudo/PAM,
hold-2s-to-lock, dual-host binding with a switch fingerprint, the on-device SSH key vault
(verified against a real ssh-add -L and a signed authentication), and the TOTP vault.

Developed and tested against immurok's macOS app. Windows and Linux use the same
protocol and are expected to work, but are untested here.

Known limitations

  • Keys are stored in plaintext NVS. Flash and NVS encryption are off, so physical
    possession of the device means the pairing keys, SSH private keys and TOTP secrets can
    be read out with esptool read_flash. Deliberate trade for a personal build; read the
    README's security section before trusting it further than that.
  • Not security-audited. Has run on exactly one device.
  • Reports firmware version 99.0.0 over BLE so the companion app never offers an OTA
    image this hardware couldn't apply. That is unrelated to this release tag.
  • The sensor's own green flash on a successful match cannot be suppressed — it is the
    module's firmware, not this one.

Assets

File Use
immurok-esp32-v1.0.0-merged.bin Start here. Everything, flashed at 0x0
immurok-esp32-v1.0.0-app.bin App only, offset 0x20000
bootloader.bin Offset 0x0 (three-file flow)
partition-table.bin Offset 0x8000 (three-file flow)
SHA256SUMS Checksums for all of the above

The printed case (from tinytouch, MIT) is in
hardware/case/ in the repository.

Assets 7
Loading