onlyn00bs-badge

beacon.h (3478B)

---

 #pragma once
 #include <Arduino.h>
 #include <string.h>
 #include <stddef.h>
 #include "mbedtls/md.h"      // mbedTLS ships inside the ESP32 Arduino core
 #include "config.h"
 #include "pet.h"             // PET_FACE_MAX — beacons carry the sender's pet face
 
 // ─────────────────────────────────────────────────────────────────────────
 //  Beacon wire format (fixed size, broadcast over ESP-NOW ~1/sec).
 //
 //  The signed region is everything before `tag`. The receiver recomputes
 //  HMAC-SHA256(PSK, signed_region) and constant-time-compares against `tag`.
 //  Unverified beacons are dropped before they ever touch the peer table.
 //
 //  `counter` is a freshness hint (replay deterrent). With a symmetric group
 //  key the real guarantee is "this came from a holder of our key" — which is
 //  exactly the friends-vs-the-con threat model. Upgrade path to per-badge
 //  Ed25519 identities is noted in the README.
 // ─────────────────────────────────────────────────────────────────────────
 
 #define BEACON_MAGIC    0xB1
 #define BEACON_VERSION  2           // v2: added pet + pet_face (v1 badges won't verify)
 #define TAG_LEN         16          // HMAC-SHA256 truncated to 128 bits
 
 #pragma pack(push, 1)
 struct Beacon {
   uint8_t  magic;                   // BEACON_MAGIC — cheap pre-filter
   uint8_t  version;                 // BEACON_VERSION
   uint32_t counter;                 // monotonic-ish freshness hint
   uint8_t  handle_len;              // 1..HANDLE_MAX_LEN
   char     handle[HANDLE_MAX_LEN];  // zero-padded; padding is part of the MAC
   uint8_t  pet;                     // sender's pet index (0..PET_BUILTIN_N; ==N means custom)
   char     pet_face[PET_FACE_MAX];  // sender's pet idle face, zero-padded (renders any pet)
   uint8_t  tag[TAG_LEN];            // signature over the bytes above
 };
 #pragma pack(pop)
 
 // Bytes covered by the signature = everything up to (not including) `tag`.
 static inline size_t beacon_signed_len() { return offsetof(Beacon, tag); }
 
 static inline void beacon_hmac(const Beacon* b, uint8_t out[32]) {
   const mbedtls_md_info_t* info = mbedtls_md_info_from_type(MBEDTLS_MD_SHA256);
   mbedtls_md_hmac(info, GROUP_PSK, GROUP_PSK_LEN,
                   (const uint8_t*)b, beacon_signed_len(), out);
 }
 
 // Fill `tag` for an outgoing beacon. Caller must zero-pad `handle` first.
 static inline void beacon_sign(Beacon* b) {
   uint8_t full[32];
   beacon_hmac(b, full);
   memcpy(b->tag, full, TAG_LEN);
 }
 
 // Constant-time compare — don't leak the tag via early-exit timing.
 static inline bool ct_equal(const uint8_t* a, const uint8_t* b, size_t n) {
   uint8_t diff = 0;
   for (size_t i = 0; i < n; i++) diff |= a[i] ^ b[i];
   return diff == 0;
 }
 
 // Validate structure + signature. `len` is the received byte count.
 static inline bool beacon_verify(const Beacon* b, size_t len) {
   if (len < sizeof(Beacon))                       return false;  // runt
   if (b->magic   != BEACON_MAGIC)                 return false;
   if (b->version != BEACON_VERSION)               return false;
   if (b->handle_len == 0 || b->handle_len > HANDLE_MAX_LEN) return false;
   uint8_t full[32];
   beacon_hmac(b, full);
   return ct_equal(full, b->tag, TAG_LEN);
 }