Skip to content

Releases

v2.0.0 — 128-bit nonces, ChaCha20-Poly1305 enrollment

Choose a tag to compare

@Nexusdeveloper902 Nexusdeveloper902 released this 11 Oct 18:25

Protocol v2 (breaking — phone app, reader firmware, and backend migrate together)

  • 16-byte challenge nonces: CHALLENGE is now 80 10 00 00 10 + 16 bytes (21 B total). Collision probability negligible at any plausible scale.
  • Enrollment wrap is now ChaCha20-Poly1305 AEAD (RFC 8439, dependency-free, pinned against RFC §2.3.2/§2.4.2/§2.8.2 vectors): key derivation binds credId, AAD binds (credId, nonce), 120-hex output (24 nonce + 64 ct + 32 tag). Wrong secrets and any tampering fail closed at unwrap. v1 XOR-HMAC wrap retired.
  • New pinned interop vector (computed independently via Python hmac + BoringSSL ChaCha20-Poly1305) — verify ports against it before touching hardware.

Review hardening (from the API security assessment)

  • Typed CredentialKind enum replaces stringly lastKind() (deprecated shim kept; Tap carries kind + isHce convenience).
  • verifyProof() = cryptographic validity only; replay needs an atomic backend nonce claim (unique constraint); new authoritative docs/SECURITY.md.
  • Production RNG policy, per-device high-entropy reader secrets, relay/proximity limits, radio-only healthy(), borrowed-reference lifetimes, API stability policy, unwrapKeyHex() server mirror.

Verification

  • 106 native tests green (pio test -e native), incl. RFC 8439 vectors and AEAD tamper rejection.
  • BasicTap/HceEnroll cross-compile for esp32dev and megaatmega2560 (CI).
  • CI now also runs on v* tags.

v1.2.0 — configuration without source edits, AID at runtime, adoption aliases

Choose a tag to compare

@Nexusdeveloper902 Nexusdeveloper902 released this 11 Oct 01:14

Configuration without touching source

Everything in src/Rc522HceConfig.h is #ifndef-guarded, so a build flag always wins, a board preset applies when you do not override, and defaults apply otherwise — for default-constructed readers too, so Rc522HceReader radio; is always correctly wired.

  • -DRC522HCE_SS_PIN / RST / SCK / MISO / MOSI — wiring per build flag
  • -DRC522HCE_AID_BYTES=0xF0,… — the AID your phone app serves
  • -DRC522HCE_DEBOUNCE_MS, -DRC522HCE_REINIT_INTERVAL_MS, -DRC522HCE_HCE_SETTLE_MS
  • Board presets auto-detected: ESP32, AVR (Mega/UNO-Nano), ESP8266, RP2040, STM32 — opt out with -DRC522HCE_NO_BOARD_PRESET

This closes the silent-wrong-pins trap: a reader used on a non-default board is wired by the preset or your flags, never by a DevKit default.

AID at runtime

reader.setAid(bytes, len) changes the AID the reader SELECTs with no reflash (1..11 bytes, rejected otherwise); selectedAid()/selectedAidLen() reports what a phone must serve. buildSelectAidWith() builds the frame for an explicit AID, and NfcReader carries aid()/aidLen()/setAid() so every transport exposes the same surface.

Adoption aliases

Optional CompatNames.h for dropping this into an existing codebase: Presence::Rc522NfcReader, Presence::Hce::*, Presence::HceProof, Presence::Signer::toHex become exact aliases of the same types, so existing call sites keep compiling and values cross the seam both ways. Included by no other header, so it cannot become a hidden dependency; Arduino-only aliases are guarded so it still compiles in host tests.

Also

  • TsLog.h is now part of the library (timestamped Print decorator for the diagnostics sink).
  • 95 host tests (was 86): new suite pins the config defaults, board-preset/pin invariants, AID override and length limits, and the alias layer's type identity.
  • CI: self-contained (no third-party actions) — installs PlatformIO Core into a venv, runs pio test -e native, cross-compiles both examples on ESP32 and AVR Mega, and compiles a build-flag-rewired ESP32-CAM sketch to prove config needs no source edits.

v1.1.0 — RC522-HCE, protocol on the public API

Choose a tag to compare

@Nexusdeveloper902 Nexusdeveloper902 released this 11 Oct 00:07

Rename

Repo renamed esp32-rc522-hce → rc522-hce. The name no longer claims ESP32: the driver, docs, wiring tables and library metadata are board-neutral (ESP32, ESP8266, AVR UNO/Nano/Mega, STM32, RP2040, nRF52, Teensy — anything with an Arduino core and SPI). Old URLs redirect automatically.

The HCE protocol is now exposed on the API

Everything a phone app, reader firmware, or backend needs is reachable from the single public header, instead of being spread across docs and driver internals:

  • HceReader::verifyProof(proof, credId, credKey) — backend verification of a relayed tap, constant-time. This is where the per-credential key is used; the reader never holds it.
  • HceReader::aid() / aidLen() — the AID a phone's HCE app must serve.
  • HceReader::nonceLen() / macLen() / keyLen() / maxCredentialLen() — protocol lengths (8 / 32 / 32 / 32).
  • HceReader::statusWordName(sw1, sw2) — decodes 9000, 6A82, 6A88, 6985, 6700, 6D00, 6E00 for operator-facing messages.
  • HceReader::toHex() / fromHex() — wire transcripts and wrapped keys are hex.
  • HceReader::selfCheckVector() and TestVector::* — the pinned interop vector as named constants: credId, key, nonce, MAC, reader secret, wrapped key.
  • README gained "API at a glance" and "Where the HCE key lives": phone holds K_cred, reader holds only the enrollment wrap secret, server verifies and unwraps.

Tests

86 host-side tests (was 78). The new public-API suite includes only HceReader.h, so if the facade ever stops re-exporting something the docs promise, the build fails instead of the docs quietly lying.

Verified builds

  • pio test -e native — 86/86 passing, no board needed
  • ESP32 (esp32dev) — builds, 23% flash
  • Arduino Mega — builds, 31% RAM (UNO compiles but overflows its 2 KB RAM; documented)

Note: v1.0.0 predates the rename, so its source carries the old repo name. Prefer this release.

v1.0.0 — initial release

Choose a tag to compare

@Nexusdeveloper902 Nexusdeveloper902 released this 10 Oct 23:43

First public release of the RC522 + Android-HCE reader library.

Highlights:

  • HceReader facade: configure once, then read() — one tap per physical touch, with the server-bound relay proof
  • Phone-as-credential: SELECT AID + HMAC-SHA256 challenge-response; reader holds no key, the server verifies
  • Enrollment mode: one-time key hand-off, wrapped under the reader secret, never logged raw
  • Pure-C++ core (protocol, ISO-DEP framing, debounce, key-wrap) with 78 host-side tests: pio test -e native
  • Portable driver: any SPI-capable Arduino core (ESP32/ESP8266/AVR/RP2040/STM32), injectable RNG
  • Bench-hardened radio behavior: park-and-activate RATS, S(WTX) handling, FIFO late-answer salvage, 1 MHz SPI

Docs: docs/HCE_PROTOCOL.md (phone-app contract + shared test vector), docs/WIRING.md (pin tables per board, 2-3 cm tap distance).