Merge pull request #17 from lpiob/feat/custom-presence-pin

feat(presence): add configurable GPIO presence pin

Author: TheMaxMur

README.md

@@ -92,7 +92,7 @@ Full reasoning: [docs/threat-model.md](docs/threat-model.md).
 
 Any RP2350 board with USB. Developed and tested on the **Waveshare RP2350-One**
 (WS2812 status LED on GPIO16; boards without an LED run fine). A different flash
-size or LED pin is a one-line build knob. Details:
+size, LED pin, or presence-button GPIO is a one-line build knob. Details:
 [docs/hardware.md](docs/hardware.md).
 
 ## Quick start

docs/architecture.md

@@ -113,11 +113,11 @@ reader name.
 
 ## User presence
 
-One BOOTSEL button, shared by all applets through a `UserPresence` trait the
-firmware implements once: FIDO operations, OpenPGP UIF, PIV touch policies,
-OATH touch accounts, and OTP slot typing (1–4 presses select the slot) all
-gate on it. The no-touch build (`--features no-touch`) auto-confirms — for
-test rigs, not for daily use.
+One presence button (BOOTSEL by default, or `PRESENCE_PIN`), shared by all 
+applets through a `UserPresence` trait the firmware implements once: FIDO 
+operations, OpenPGP UIF, PIV touch policies, OATH touch accounts, and OTP slot 
+typing (1–4 presses select the slot) all gate on it. The no-touch build 
+(`--features no-touch`) auto-confirms — for test rigs, not for daily use.
 
 ## Provenance
 

docs/build.md

@@ -26,7 +26,7 @@ flowchart TD
 
 | Feature | Default | Effect |
 |---|---|---|
-| `no-touch` | off | Auto-confirm user presence — FIDO operations (makeCredential, getAssertion, U2F, reset, selection) and OpenPGP UIF data objects no longer require a press of the BOOTSEL button. **Requiring a touch is the default and is not a feature**; `--features no-touch` is the explicit escape hatch for the automated suites (`tests/`, python-fido2, OpenPGP card tests), which cannot press a button and would hang on the (default) touch build. **Never ship a no-touch build.** |
+| `no-touch` | off | Auto-confirm user presence — FIDO operations (makeCredential, getAssertion, U2F, reset, selection) and OpenPGP UIF data objects no longer require a press of the presence button (BOOTSEL by default, or `PRESENCE_PIN` when set). **Requiring a touch is the default and is not a feature**; `--features no-touch` is the explicit escape hatch for the automated suites (`tests/`, python-fido2, OpenPGP card tests), which cannot press a button and would hang on the (default) touch build. **Never ship a no-touch build.** |
 | `advertise-pqc` | off | Prepends ML-DSA-44 (COSE −48) to the getInfo `algorithms` list. Off by default because released Firefox versions abort the *entire* getInfo parse on an unknown COSE id and report the authenticator broken. **PQC capability is on regardless of this flag** — makeCredential negotiates −48 from the request's `pubKeyCredParams`; the flag only controls advertising. |
 | `fips-profile` | off | Bakes a locked FIPS-style policy into the image: ES256K (secp256k1) leaves the FIDO menu, the minimum PIN rises to 6, the vendor seed *export* is refused, and PIV refuses new 3DES management keys and RSA-1024. The default build is unchanged; with secure boot the policy is sealed by your signature. A profile, **not** a FIPS validation — details and rationale: [guides/fips.md](guides/fips.md). |
 | `strict-up` | off | Require a touch on **every** `getAssertion`. By default RS-Key honors the platform's silent pre-flight probe (`up:false`): it returns the discovery assertion with no touch and the UP flag clear, so a WebAuthn login with an `allowCredentials` (non-resident) credential is a **single** touch — matching the CTAP2 spec and YubiKey. With `strict-up` the button is polled even for that probe, so such a login asks for **two** touches (one for the probe, one for the real assertion). A deliberately stricter "every assertion needs an explicit gesture" stance for those who want it; it is **not** spec-conformant for `up:false`. Resident-credential / passkey logins are a single touch either way. `fido-conformance` enables this implicitly (the conformance pass was validated with it). |
@@ -42,6 +42,7 @@ flowchart TD
 | `XOSC_DELAY_MULT` | `128` | `1..=1024` | Crystal-oscillator startup-delay multiplier ("delayed boot"). A longer settle wait is intended to harden the early-boot clock-switch window against glitch/fault injection. 128 is the embassy default. |
 | `FLASH_SIZE` | `4M` | bytes, `0xHEX`, or `<n>K`/`<n>M` | External QSPI flash size. build.rs regenerates `memory.x` from it — the KV store stays a fixed 1.5 MB at the top, the code region is the rest. `4M` reproduces the checked-in layout byte-for-byte. Use this for boards with a different flash chip (e.g. `8M`); must be ≥ ~2 MB and ≤ 16 MB. |
 | `LED_PIN` | `16` | `0..=29` | The status-LED GPIO for the `ws2812` and `gpio` backends (RP2350A). Default GPIO16 is the Waveshare RP2350-One. Point it at a free GPIO on boards that use 16 for something else; the indicator simply drives whatever pin you pick. (Unused by `pimoroni`, which has fixed PWM pins, and by `none`.) |
+| `PRESENCE_PIN` | `bootsel` | `bootsel` or `0..=29` | User-presence input source. Default `bootsel` keeps the BOOTSEL hardware-button path. Set a GPIO number for a dedicated button (active-low with internal pull-up). Example: `PRESENCE_PIN=0` for a button to ground on GPIO0. |
 | `LED_KIND` | `ws2812` | `ws2812` / `gpio` / `pimoroni` / `none` | The LED driver backend, and the **boot default** — a non-`none` build compiles all three so the driver/pin/order are runtime-switchable via `rsk hw` / PicoForge (see below). `ws2812` = a single addressable RGB on `LED_PIN` (the Waveshare default). `gpio` = a plain on/off LED on `LED_PIN` — hue/brightness collapse to lit/unlit, but the blink *pattern* still distinguishes statuses. `pimoroni` = a 3-pin PWM RGB (Pimoroni Tiny 2350: R=GPIO18, G=GPIO19, B=GPIO20, common-anode). `none` = no indicator (the status engine still runs; nothing renders it, and the phy LED fields are ignored). |
 | `LED_ORDER` | `rgb` | `rgb` / `grb` | WS2812 wire byte order (`ws2812` backend only). The Waveshare RP2350-One is unusually `rgb` (the default); standard WS2812B parts (e.g. the TenStar RP2350-USB) are `grb`. If a `ws2812` board comes up with red and green swapped (blue fine), flip this to `grb`. |
 | `MAX_LEDS` | `8` | `1`–`64` | PIO state-machine and frame-buffer ceiling for addressable LEDs. The **actual** connected count is set at runtime via `rsk hw --led-num` and must be ≤ `MAX_LEDS`. Default 8 covers the common 1–8 range; boards with more (up to 64) override this.|
@@ -157,7 +158,7 @@ Two caveats:
        { name = "fw"; vidpid = "Nitro3"; fwVersion = "2.0.0"; }'
   ```
   Knobs: `vidpid`, `usbVid`, `usbPid`, `fwVersion`, `xoscDelayMult`, `flashSize`,
-  `ledPin`, `fakeMkek`, `fakeDevk` (mirroring the env vars above). As a convenience each also falls
+  `ledPin`, `presencePin`, `fakeMkek`, `fakeDevk` (mirroring the env vars above). As a convenience each also falls
   back to the like-named env var, so `VIDPID=Pico nix build --impure .#firmware`
   works for a quick throwaway — but the declarative arg is the reproducible path
   and needs no `--impure`.

docs/hardware.md

@@ -21,14 +21,15 @@ cable are enough.
 
 ## Defaults and the knobs to change them
 
-The default build targets a 4 MB flash chip with the LED on GPIO16 and assumes a
-standard 12 MHz crystal. For a different board, two compile-time knobs usually
-cover it:
+The default build targets a 4 MB flash chip with the LED on GPIO16, uses BOOTSEL
+for user presence, and assumes a standard 12 MHz crystal. For a different board,
+three compile-time knobs usually cover it:
 
 | Knob | Default | When to change it |
 |---|---|---|
 | `FLASH_SIZE` | `4M` | A board with a different QSPI flash chip (e.g. `8M`). `build.rs` regenerates `memory.x` from it. Must be ≥ ~2 MB and ≤ 16 MB. |
 | `LED_PIN` | `16` | A board that uses GPIO16 for something else, or wires its addressable LED elsewhere (RP2350A: GPIO `0..=29`). |
+| `PRESENCE_PIN` | `bootsel` | A board with a dedicated user-presence button on a GPIO. Set a pin number (`0..=29`) for an active-low button with pull-up (e.g. `0` for GPIO0-to-GND). |
 | `LED_KIND` | `ws2812` | `ws2812` (addressable RGB, default), `gpio` (plain on/off), `pimoroni` (3-pin PWM RGB), or `none` (no indicator). See [build.md](build.md). |
 | `LED_ORDER` | `rgb` | A `ws2812` board whose red and green come out swapped (blue fine): set `grb` (the WS2812B standard). The Waveshare RP2350-One is `rgb`; most other parts are `grb`. |
 | `MAX_LEDS` | `8` | A board with **more than 8** daisy-chained addressable LEDs. The buffer ceiling; the actual connected count is set at runtime ([guides/led.md](guides/led.md)). |
@@ -39,6 +40,9 @@ env FLASH_SIZE=8M LED_KIND=gpio LED_PIN=25 cargo build --release -p firmware
 
 # example: a 16 MB TenStar RP2350-USB — WS2812 on GP22, standard GRB order
 env FLASH_SIZE=16M LED_PIN=22 LED_ORDER=grb cargo build --release -p firmware
+
+# example: WS2812 on GP22 and a dedicated touch button on GP0
+env LED_PIN=22 PRESENCE_PIN=0 cargo build --release -p firmware
 ```
 
 The four LED knobs (`LED_PIN` / `LED_KIND` / `LED_ORDER` / `MAX_LEDS`) set only the

docs/quickstart.md

@@ -33,9 +33,9 @@ picotool uf2 convert target/thumbv8m.main-none-eabihf/release/firmware -t elf fi
 ```
 
 This is the **touch build**: FIDO operations (registering, logging in) require
-a press of the BOOTSEL button — it stands in for the touch sensor on a typical
-hardware key. For a no-touch build (needed by the automated test suites, or if
-your board is hard to reach) add `--features no-touch`. All build knobs:
+a press of the presence button (BOOTSEL by default; set `PRESENCE_PIN=<gpio>` for
+a dedicated GPIO button). For a no-touch build (needed by the automated test
+suites, or if your board is hard to reach) add `--features no-touch`. All build knobs:
 [build.md](build.md).
 
 ## 2. Flash

docs/unsafe.md

@@ -7,32 +7,33 @@ contained. Adding a new `unsafe` requires updating this page. (Safe Rust rules
 out memory-corruption bugs in this code; it is not a security audit — see the
 [threat model](threat-model.md).)
 
-**Runtime sites: 9** — three concerns in the firmware proper (the interrupt
+**Runtime sites: 10** — four concerns in the firmware proper (the interrupt
 handler pair counted honestly as two), two for the per-core prime sieves, one
 in the RSA assembly FFI, two in the standalone flash-wipe tool.
 
 ```mermaid
 flowchart TB
-    subgraph fw["firmware/src/main.rs"]
+    subgraph fw["firmware/src/main.rs + firmware/src/presence.rs"]
       a["interrupt executor (×2)"]
       b["Send for SendUsb"]
       c["heap init"]
+      d["GPIO presence pin steal"]
     end
     subgraph kg["firmware/src/core1.rs"]
-      d["per-core prime sieves (×2)"]
+      e["per-core prime sieves (×2)"]
     end
     subgraph asm["rsk-rsa-asm"]
-      e["modexp FFI"]
+      f["modexp FFI"]
     end
     subgraph wipe["rsk-wipe"]
-      f["raw flash erase/program (×2)"]
+      g["raw flash erase/program (×2)"]
     end
 ```
 
 The `unsafe` lives only in plumbing — none of it is in a parser, applet, crypto
 wrapper, or the filesystem.
 
-## Firmware (`firmware/src/main.rs`)
+## Firmware (`firmware/src/main.rs`, `firmware/src/presence.rs`)
 
 ### 1–2. The high-priority interrupt executor
 
@@ -78,9 +79,25 @@ static buffer used by nothing else.
 *Safe alternative:* none; every embedded allocator initializes this way.
 *Containment:* one call, before any allocation can happen.
 
+### 5. GPIO presence pin type-erasure
+
+```rust
+let any = unsafe { AnyPin::steal(pin) };
+```
+
+The optional `PRESENCE_PIN=<gpio>` path chooses the presence button at runtime
+(instead of a concrete `PIN_n` type at compile time), so the code must convert a
+numeric pin to embassy's type-erased `AnyPin`. `AnyPin::steal` is `unsafe`
+because the caller must guarantee unique ownership of that hardware pin.
+*Safe alternative:* none for a runtime-selected GPIO; the safe constructors
+require a statically known pin type.
+*Containment:* one call site in `BootselPresence::new_gpio`, gated by pin-range
+validation and the single-owner invariant from `main` (the chosen presence pin
+is never handed to the LED/backends; an LED/presence conflict panics at boot).
+
 ## Firmware dual-core keygen (`firmware/src/core1.rs`)
 
-### 5–6. The per-core prime sieves
+### 6–7. The per-core prime sieves
 
 ```rust
 static mut CORE0_SIEVE: IncrementalSieve = IncrementalSieve::new();
@@ -109,7 +126,7 @@ a composite through to the strong-MR/Lucas test, which still rejects it.
 
 ## RSA assembly FFI (`crates/rsk-rsa-asm/src/lib.rs`)
 
-### 7. The modexp call
+### 8. The modexp call
 
 On-card RSA key generation needs hundreds of modular exponentiations over
 1024–2048-bit candidates; the pure-Rust path was ~7× too slow on the
@@ -125,7 +142,7 @@ tests exercise the same API safely.
 
 ## Flash wiper (`rsk-wipe/src/main.rs`)
 
-### 8–9. Raw flash erase/program in a critical section
+### 9–10. Raw flash erase/program in a critical section
 
 The wiper's entire job is to erase the flash the firmware lives on, from a
 RAM-resident image. It calls the ROM flash-erase/program routines inside

firmware/build.rs

@@ -66,6 +66,17 @@ fn main() {
     println!("cargo:rustc-env=PK_LED_PIN={led_pin}");
     println!("cargo:rerun-if-env-changed=LED_PIN");
 
+    // User-presence source: default BOOTSEL, or `PRESENCE_PIN=<gpio>` for an
+    // active-low GPIO button (internal pull-up). Encoded as two numeric envs so
+    // `main` can parse them with the existing const decimal parser.
+    let (presence_is_gpio, presence_pin) = resolve_presence_pin();
+    println!(
+        "cargo:rustc-env=PK_PRESENCE_IS_GPIO={}",
+        if presence_is_gpio { 1 } else { 0 }
+    );
+    println!("cargo:rustc-env=PK_PRESENCE_PIN={presence_pin}");
+    println!("cargo:rerun-if-env-changed=PRESENCE_PIN");
+
     // LED backend (default `ws2812`, the Waveshare RP2350-One). Selected at
     // compile time so only the chosen driver — and its dependencies (PIO, PWM) —
     // is built. `gpio` = a plain on/off indicator, `pimoroni` = a 3-pin PWM RGB
@@ -190,6 +201,24 @@ fn resolve_led_pin() -> u8 {
     v
 }
 
+/// Resolve `PRESENCE_PIN` to either BOOTSEL (unset / `bootsel`) or a GPIO
+/// number `0..=29` for an active-low button with internal pull-up.
+fn resolve_presence_pin() -> (bool, u8) {
+    let raw = env::var("PRESENCE_PIN").unwrap_or_default();
+    let v = raw.trim().to_ascii_lowercase();
+    if v.is_empty() || v == "bootsel" {
+        return (false, 0);
+    }
+    let pin = v.parse::<u8>().unwrap_or_else(|_| {
+        panic!("PRESENCE_PIN={raw:?} must be `bootsel` or a GPIO number 0..=29")
+    });
+    assert!(
+        pin <= 29,
+        "PRESENCE_PIN={pin} out of range 0..=29 (RP2350A GPIOs)"
+    );
+    (true, pin)
+}
+
 /// Resolve `LED_KIND` (the LED driver backend) to a known value; defaults to
 /// `ws2812`. One of: `ws2812` (addressable RGB on `LED_PIN`), `gpio` (a plain
 /// on/off LED on `LED_PIN`), `pimoroni` (3-pin PWM RGB, Pimoroni Tiny 2350), or

firmware/src/ccid_handler.rs

@@ -49,8 +49,9 @@ pub struct CcidApplets<'a> {
 impl<'a> CcidApplets<'a> {
     /// `serial_id` is the device chip id (its first 4 bytes go into the OpenPGP
     /// full AID); `rng` is the hardware TRNG shared with the CTAPHID handler.
-    /// The three `presence` params are the same BOOTSEL button behind per-applet
-    /// traits (the caller's concrete `&RefCell` coerces to each).
+    /// The three `presence` params are the same physical presence source (BOOTSEL
+    /// by default, optionally a GPIO button) behind per-applet traits (the
+    /// caller's concrete `&RefCell` coerces to each).
     #[allow(clippy::too_many_arguments)] // one-time wiring from the worker
     pub fn new(
         fs: &'a RefCell<Store>,
@@ -75,8 +76,8 @@ impl<'a> CcidApplets<'a> {
             // Touch-flagged OATH credentials gate CALCULATE on the same button.
             oath: OathApplet::new(serial_id, serial_hash, otp_key, rng, oath_presence),
             otp: OtpApplet::new(serial_id, otp_presence),
-            // PIV reuses the OpenPGP user-presence trait, so the same BOOTSEL
-            // `presence` drives its slot/management touch policies.
+            // PIV reuses the OpenPGP user-presence trait, so the same presence
+            // source drives its slot/management touch policies.
             piv: PivApplet::new(serial_id, serial_hash, otp_key, rng, presence),
             // The recovery/provisioning interface: phy config, flash stats,
             // secure-boot status, session RTC, device-key attestation, reboot.

firmware/src/handler.rs

@@ -116,7 +116,8 @@ pub struct AppletHandler<'a> {
     /// Cross-message PIN/UV-auth state (PIN token, the ephemeral ECDH key …);
     /// lives for one power cycle.
     fido_state: rsk_fido::FidoState,
-    /// Physical user presence (BOOTSEL), shared with the OpenPGP applet through a
+    /// Physical user presence (BOOTSEL by default, optionally a GPIO button),
+    /// shared with the OpenPGP applet through a
     /// `RefCell`; borrowed only for a touch wait inside one dispatch.
     presence: &'a RefCell<dyn rsk_fido::UserPresence>,
     serial_id: [u8; 8],

firmware/src/main.rs

@@ -116,6 +116,8 @@ const XOSC_DELAY_MULT: u32 = env_u32(env!("PK_XOSC_DELAY_MULT"));
 // numbering (1=gpio, 2=pimoroni, 3=ws2812).
 #[cfg(not(led_kind = "none"))]
 const BUILD_LED_PIN: u8 = env_u16(env!("PK_LED_PIN")) as u8;
+const BUILD_PRESENCE_IS_GPIO: bool = env_u16(env!("PK_PRESENCE_IS_GPIO")) != 0;
+const BUILD_PRESENCE_PIN: u8 = env_u16(env!("PK_PRESENCE_PIN")) as u8;
 #[cfg(led_kind = "ws2812")]
 const BUILD_DRIVER: u8 = 3;
 #[cfg(led_kind = "gpio")]
@@ -310,7 +312,7 @@ async fn main(_spawner: Spawner) {
     config.serial_number = Some("rs-key-0001");
     config.max_power = 100;
     config.max_packet_size_0 = 64;
-    config.device_release = 0x0781; // bcdDevice: our build counter
+    config.device_release = 0x0782; // bcdDevice: our build counter
 
     let mut builder = Builder::new(
         driver,
@@ -405,6 +407,12 @@ async fn main(_spawner: Spawner) {
             .and_then(|p| p.led_gpio)
             .filter(|&g| g <= 29)
             .unwrap_or(BUILD_LED_PIN);
+        if BUILD_PRESENCE_IS_GPIO && BUILD_PRESENCE_PIN == led_gpio {
+            panic!(
+                "PRESENCE_PIN={} conflicts with active LED pin",
+                BUILD_PRESENCE_PIN
+            );
+        }
         // PHY led_driver (1=gpio, 2=pimoroni, 3=ws2812) overrides the build kind;
         // anything else (unset, or the N/A esp32 value) keeps the build default.
         let led_driver = match phy.as_ref().and_then(|p| p.led_driver) {
@@ -522,7 +530,12 @@ async fn main(_spawner: Spawner) {
 
     core1::spawn(p.CORE1);
 
-    let presence_ref = PRESENCE.init(RefCell::new(BootselPresence::new(p.BOOTSEL)));
+    let presence = if BUILD_PRESENCE_IS_GPIO {
+        BootselPresence::new_gpio(BUILD_PRESENCE_PIN)
+    } else {
+        BootselPresence::new_bootsel(p.BOOTSEL)
+    };
+    let presence_ref = PRESENCE.init(RefCell::new(presence));
     let platform_ref = RESCUE_PLATFORM.init(RefCell::new(rescue_platform::RescuePlatform));
     let (kvm, kvc) = (kvmain_range(), kvcnt_range());
     let kv_total = (kvm.end - kvm.start) + (kvc.end - kvc.start);