Skip to content

Cryptographic Security and Provisioning

Jump to bottom
GiZano edited this page Aug 31, 2026 · 2 revisions

Cryptographic Security & Provisioning

QuakeGuard implements a Zero-Trust security model for its IoT edge nodes.

Cryptographic Identity (ECDSA)

Upon its first boot, the ESP32-C3 uses mbedtls to generate a unique ECDSA key pair using the NIST P-256 curve (secp256r1).

  • Private Key: Stored permanently in Non-Volatile Storage (NVS) to sign outgoing telemetry — never leaves the device.
  • Public Key: Extracted in DER format, hex-encoded, acting as the unforgeable sensor identity in the backend.

Automated Provisioning Handshake

  1. The device sends a POST to /devices/register with its public_key_hex, MAC address, coordinates, and ENROLLMENT_TOKEN.
  2. The backend validates the factory token and, via a geohash-based Redis fast-path (zoneindex:<geohash> prec 3 → set of zone ids) with authoritative PostGIS fallback (ST_Contains ordered by ST_Area ASC), assigns the sensor to the smallest containing polygon. When a GNSS fix exists it is the live or last-known NVS fix; otherwise coordinates may be omitted and the backend keeps NULL geometry → Unknown Region.
  3. A unique sensor_id is returned and saved to NVS (quake-config).

Automatic first-boot provisioning is the only path since v1.2.2 — the compile-time SENSOR_ID shortcut was removed.

Payload Authentication

Telemetry payloads are value:timestamp hashed via SHA-256 and signed with the private key. Payloads are identical on MQTT and serial planes ([QG:FB] frames carry the same JSON behind the marker). When the serial fallback drains, the payload is re-signed with the current software wall clock (epochAtSync+millis()) so the backend replay window accepts it.

The validate_iot_payload pipeline enforces four gates:

  1. API Key Verification: Constant-time hmac.compare_digest check on X-API-Key.
  2. Sensor Status: Verifies the sensor ID exists and is active.
  3. Anti-Replay Protection: Rejects payloads older than a 300-second threshold (403 Forbidden).
  4. Signature Verification: Python cryptography verifies ECDSA against the stored public key (DER and raw r||s tolerant).

Clone this wiki locally