How imPress protects accounts, data, devices and firmware, what you must turn on before production, and what is still open. References: docs/design/security-model.md, docs/engineering/SECURITY_REVIEW.md.

• Production checklist
• Threat overview
• Accounts and sessions
• Access control
• Secrets
• Per-device keys
• Signed firmware
• Device traffic over TLS
• Uploads
• Data protection
• The mesh
• Git history
• What is not protected
• Reporting a vulnerability

Every rule is enforced on the server, never just by hiding buttons:

backend/tests/test_route_guards.py requests every registered route without credentials (and every device route with a wrong key) and fails if one answers. Adding a route without a guard breaks the build.

The problem: with one shared key, anyone who had it (a leaked .env, or a key read out of any device's flash) could act as any device: forge answers, report fake firmware results, or impersonate a gateway.

How it works now:

sequenceDiagram
    participant D as Device
    participant B as Backend
    D->>B: POST /register (X-API-Key: shared key)
    B->>B: issue a key, store only its SHA-256
    B-->>D: {"device_id": 12, …, "device_key": "kq3V…"}
    D->>D: store it in NVS dev_key
    D->>B: POST /heartbeat (X-API-Key: its own key)
    B->>B: first use → the key is active
    Note over B: from now on the shared key is refused for this MAC,<br/>and this key is refused for any other MAC

Edge cases handled:

• A lost response: a key that was issued but never used is replaced when the device registers again with the shared key, so a lost registration response can't lock a device out.
• A reflashed device: its flash, and so its key, was erased. Reset key on the Modules page lets it enrol again.
• A stolen device: disable it. Every request for its MAC is refused, whichever key is used.
• Batches: each relayed message is accepted only for a gateway the caller may act for. Answers and votes, which carry no gateway MAC, count as the caller's own.

Required mode: IMPRESS_DEVICE_KEYS_REQUIRED=true limits the shared key to registration. Turn it on once every device runs v2.1 firmware with per-device keys, and shows own key. Older firmware stops working in this mode.

Residual risk: a device that has no key yet (or whose key was reset) can be claimed by whoever presents the shared key first.

The problem: without signatures, a device installs any image that passes the integrity checks. An attacker who can get a file accepted, or who sits between a device and the server, could run their own code on hubs and gateways.

The scheme: ESP-IDF's signed app images without hardware Secure Boot: RSA-3072 in the Secure Boot V2 format.

1. Create the site key, once:

   scripts/firmware_key.sh                      # → ~/.impress/firmware-signing/

   • signing_key.pem is the private key. Keep it offline and backed up, and never commit it.
   • signing_key.pub is the public key. Give it to the backend.

   The script refuses to overwrite an existing key, and prints the key's digest (the same value espsecure digest-sbv2-public-key gives).

2. Tell the backend, then restart it:

   # backend/.env
   IMPRESS_FIRMWARE_SIGNING_KEY=/home/impress/.impress/firmware-signing/signing_key.pub

3. Build signed images:

   IMPRESS_SIGNING_KEY=~/.impress/firmware-signing/signing_key.pem scripts/build_signed.sh class_c6
   IMPRESS_SIGNING_KEY=~/.impress/firmware-signing/signing_key.pem scripts/build_signed.sh class_s3
   scripts/verify_firmware.py firmware/class_c6/build/signed/impress_class_c6.bin --key ~/.impress/firmware-signing/signing_key.pub

   build_signed.sh starts from the project's committed sdkconfig, so partitions, flash settings and rollback are unchanged. It adds firmware/sdkconfig.defaults.signed and the key path, and writes into firmware/<project>/build/signed/.

4. Upload and deploy as usual. The Firmware page shows signed ✓ for images signed with the site key, other key for images signed with another key, and unsigned in red for images that will never be deployed.

The transition: the device that installs the first signed-profile image doesn't check that one yet. Only the images after it are checked. So run that first deployment from a trusted machine.

• Rotate: a device checks updates against the key compiled into the image it is running. ESP-IDF allows up to three signature blocks per image (espsecure sign-data --version 2 --append-signatures):

  1. Deploy an image built with the new key and also signed with the old key.
  2. Switch the backend to the new public key.

  This has not been rehearsed on hardware yet: try it on one bench device first.

• Turn it off: sign a normal-profile build with the current key (espsecure sign-data --version 2 --keyfile signing_key.pem), deploy it, then clear IMPRESS_FIRMWARE_SIGNING_KEY.

• Key lost: devices on the signed profile can only be updated over USB (Recovery Procedures).

The backend's verifier uses only Python's standard library. It is tested against images signed by the real espsecure.py (backend/tests/fixtures/signing), including nine kinds of tampering. CI builds and verifies a signed gateway image with a throwaway key on every change.

The problem: by default, hubs and gateways talk to the backend over plain http:// and ws://. Answers, enrollment numbers, device keys and firmware downloads cross the school network in clear, and a device can't tell whether it is talking to the real server.

Turning it on:

1. Serve TLS: a reverse proxy (Installation → TLS), or uvicorn directly:

   IMPRESS_SSL_CERTFILE=/etc/impress/server.crt IMPRESS_SSL_KEYFILE=/etc/impress/server.key \
     IMPRESS_HOST=0.0.0.0 IMPRESS_PORT=443 scripts/start.sh

   Check it:

   scripts/smoke_test.py --base https://impress.example.edu --password … [--cafile ca.pem]

2. Configure the gateway and hub firmware: idf.py menuconfig → Backend Server:

   • enable Use HTTPS / WSS to reach the backend;

   • set BACKEND_HOST to the name in the certificate, and BACKEND_PORT to the TLS port;

   • choose how the device trusts the server:

     Choice	When	You provide
     Public certificate authorities	the server's certificate comes from a public CA (e.g. Let's Encrypt)	nothing: ESP-IDF's CA bundle is built in
     certs/backend_ca.pem	a private CA, or a self-signed certificate	the CA certificate at firmware/<project>/certs/backend_ca.pem before building; it is embedded in the image (.pem files are git-ignored)

3. Build and deploy over the air (signed, if signing is on). Deploy only after the server serves TLS on the configured port. Otherwise the gateway can't reach the backend, fails its health check and rolls back: that's safe, but noisy.

Behaviour:

• Every request to the backend uses it: registration, heartbeats, batches, the WebSocket, firmware checks and downloads.
• Certificate checks: the device checks the server's certificate and host name. A mismatch is a connection error, logged and retried, never a fallback to HTTP.

CI checks both sides on every change:

• Server: it starts the server with a throwaway certificate and runs the full smoke test over HTTPS, then checks that a client without the CA is refused.
• Firmware: it builds the gateway with public-CA trust and the hub with an embedded CA.

ESP-NOW frames are not authenticated or encrypted. A rogue module can claim any enrollment number and answer for that student. The backend limits the damage:

• answers count only for registered students;
• only once per question;
• only for an active quiz.

It can't tell a rogue module from a real one. Making the mesh tamper-proof (for example a per-class key with an HMAC over each frame) is a possible future step, not part of v2.1.

Databases containing user and session data were committed to the repository before v2. Since v2 they are git-ignored and session tokens are stored hashed, but the old commits still hold them. If the repository is or will be public:

pip install git-filter-repo
git filter-repo --invert-paths --path backend/impress.db --path backend/impress.db.bak-pre-ist --path impress.db
git push --force --all && git push --force --tags      # coordinate with everyone: they must re-clone

Then rotate every password those databases held. This rewrites history and needs a force-push, which is the repository owners' decision.

• Physical attacks on devices: reading flash (keys, Wi-Fi passwords) or replacing the bootloader. That needs flash encryption and hardware Secure Boot, which are irreversible and not enabled.
• The radio mesh: see The mesh.
• Insiders with admin rights: admins can deploy firmware and see every class. Use as few admin accounts as you can, and read the activity log.
• Denial of service on the network or the radio.

Please don't open a public issue with exploit details. Contact the repository owners privately. A public issue can describe the area without the details (for example, #66 was filed that way).