Repository navigation
Releases
v2.0.0 — 128-bit nonces, ChaCha20-Poly1305 enrollment
Protocol v2 (breaking — phone app, reader firmware, and backend migrate together)
- 16-byte challenge nonces:
CHALLENGEis now80 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
CredentialKindenum replaces stringlylastKind()(deprecated shim kept;Tapcarrieskind+isHceconvenience). verifyProof()= cryptographic validity only; replay needs an atomic backend nonce claim (unique constraint); new authoritativedocs/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/HceEnrollcross-compile foresp32devandmegaatmega2560(CI).- CI now also runs on
v*tags.
v1.2.0 — configuration without source edits, AID at runtime, adoption aliases
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.his now part of the library (timestampedPrintdecorator 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
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()andTestVector::*— 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
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).