## Por qué

Los lectores de huellas dactilares USB para Linux son escasos, caros y los
que existen (Validity, Synaptics, etc.) se basan en controladores libfprint
inestables creados mediante ingeniería inversa que se rompen con las
actualizaciones de firmware del proveedor. El protocolo del Grow R503 es **público**,
el lado de Arduino es tu propio código, y la capa de compatibilidad libfprint es solo D-Bus.

También terminas con un lector de huellas dactilares cuyo código fuente puedes leer de arriba
a abajo.

## Lista de materiales

| Pieza | Notas | Coste aprox. |
|------|-------|------|
| Sensor de huellas dactilares capacitivo Grow R503 | El redondo con el anillo RGB | ~$10 |
| Placa Arduino Uno R3 / Nano / Mega / cualquier placa ATmega328 | Cualquier placa que ejecute SoftwareSerial | $5–$25 |
| 4–6 cables puente | Dupont / placa de pruebas | trivial |

Eso es todo. **Sin cambiador de nivel, sin divisor de voltaje** — consulta [`SPEC.md` §3.1](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md)
para saber por qué (la línea RX del R503 tolera 5V en la práctica; la ficha técnica miente).

## Conexiones```
R503             Arduino (Uno R3 / Nano / etc.)
----             ------------------------------
Red (VCC)        3V3
White (3.3VT)    3V3                  (touch-IC supply; shares rail with red)
Black (GND)      GND
Yellow (TXD)     D2  ── SoftwareSerial RX
Brown (RXD)      D3  ── SoftwareSerial TX   (direct — no divider!)
Blue (WAKEUP)    D4                          (optional; not used by firmware yet)

Si ambos tienen éxito, tu host puede usar la ruta de clave sellada. Si falta
`/dev/tpmrm0` (hardware antiguo, TPM deshabilitado en la BIOS o una VM sin TPM
virtual), quédate con el flujo de clave en texto plano predeterminado.

## Compilar e instalar

### 1. Grabar el firmware

Abre `firmware/r503fp/r503fp.ino` en el Arduino IDE y súbelo. O con
`arduino-cli`:```bash
# Uno R3:
arduino-cli compile --fqbn arduino:avr:uno firmware/r503fp/
arduino-cli upload  --fqbn arduino:avr:uno --port /dev/ttyACM0 firmware/r503fp/

# Nano (modern Optiboot, including most Elegoo / WAVGAT clones):
arduino-cli compile --fqbn arduino:avr:nano:cpu=atmega328 firmware/r503fp/
arduino-cli upload  --fqbn arduino:avr:nano:cpu=atmega328 --port /dev/ttyUSB0 firmware/r503fp/

# Nano with legacy 57600-baud bootloader (older clones):
#   replace `cpu=atmega328` with `cpu=atmega328old`

### 3. Instalación```bash
sudo bash pcside/daemon/dist/install.sh

I don't see any input text to translate. The chunk content appears to be missing from your message. Please provide the actual text for chunk 15/37 and I'll translate it from English to Spanish according to the rules.```bash
sudo r503d --status
# port:             /dev/r503
# firmware:         fw=1.1 fmt=2
# firmware paired:  true
# firmware counter: 42
# host key.tpm:     (absent)
# host key:         /var/lib/r503d/key
# host key.bak:     /var/lib/r503d/key.bak
# tpm device:       (absent)
# allow-pair:       (absent)

No se recibió ningún texto de entrada en este chunk.```bash
sudo r503d --status
# port:             /dev/r503
# firmware:         fw=1.1 fmt=2
# firmware paired:  true
# firmware counter: 12
# host key.tpm:     /var/lib/r503d/key.tpm
# host key:         (missing)
# host key.bak:     (missing)
# tpm device:       /dev/tpmrm0
# allow-pair:       (absent)

Tanto la Configuración de KDE (Plasma 6) como los diálogos de huellas dactilares de cuentas de usuario del Centro de Control de GNOME controlan `r503d` exactamente igual que controlan el `fprintd` estándar.

### Re-emparejamiento / rotación de claves

Si quieres una clave nueva (clave comprometida, cambio de hardware planificado, paranoia):```bash
sudo systemctl stop r503d
sudo r503d --unpair                        # framed; wipes Nano EEPROM + host key
sudo touch /etc/r503d/allow-pair
sudo r503d --pair                          # plaintext-key rotation
#  - or -
sudo r503d --pair --seal-tpm               # TPM-sealed rotation
sudo systemctl start r503d

The script stops `r503d`, reflashes `firmware/r503fp_wipe/` to wipe the
Nano EEPROM, reflashes the main firmware, creates `/etc/r503d/allow-pair`,
runs `r503d --reseal-tpm` to generate a fresh key sealed to the *current*
PCR7, and starts the daemon back up. Tiempo total: ~90 segundos. Las huellas
inscritas se conservan: las plantillas viven en la flash del sensor R503, no
en el Nano.

El script necesita `arduino-cli` disponible. Si está instalado en
`$HOME/.local/bin` de tu usuario, se detecta automáticamente mediante
`$SUDO_USER`; de lo contrario, establece `ARDUINO_CLI=/full/path/to/arduino-cli`
antes de ejecutarlo.

### Recuperación: `state.json` perdido (desincronización del contador)

Si la clave del host está intacta pero `/var/lib/r503d/state.json` falta o se
revirtió (restauraste una copia de seguridad antigua, rm accidental), el
contador del daemon queda por detrás del `last_seen` del Nano y cada comando
enmarcado rebota con `ERR replay`. `r503d --status` lo señala; la solución es
un comando:```bash
sudo systemctl stop r503d
sudo r503d --resync                         # reads Nano last_seen, sets host counter to last_seen+1
sudo systemctl start r503d

If `sudo arduino-cli` reports command-not-found (arduino-cli lives in your
`~/.local/bin`, not on root's `PATH`), run it as
`sudo env "PATH=$PATH" arduino-cli …` or give the absolute path.

Esto no es una puerta trasera que un atacante pueda usar: volver a emparejar requiere ser root en el host (el archivo de opt-in y la CLI `--pair` ambos requieren root), por lo que un Nano reflasheado no puede pasar a ser de confianza sin que ya seas root.

### Desinstalación```bash
sudo bash pcside/daemon/dist/uninstall.sh

## Modelo de seguridad — resumen rápido

La autenticación a nivel de cable se dirige a una amenaza específica —
**"doncella malvada con cinco minutos y un Nano de repuesto"** más un proceso
local hostil en `/dev/r503` — no a estados-nación ni a atacantes de hardware
con laboratorios. Implementación de escritorio de un solo usuario con una
lista documentada de elementos fuera de alcance. El modelo de amenazas completo
se encuentra en [`SPEC.md` §13.1](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md); la evidencia de implementación y
revisión se encuentra en
[`docs/REVIEW-2026-05-28.md`](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/docs/REVIEW-2026-05-28.md). Una auditoría
adversarial separada de escalada de privilegios (2026-05-28) y su pasada de
validación/remediación por afirmación están en
[`docs/SECURITY-AUDIT-2026-05-28.html`](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/docs/SECURITY-AUDIT-2026-05-28.html)
y
[`docs/SECURITY-AUDIT-2026-05-28-VALIDATION.html`](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/docs/SECURITY-AUDIT-2026-05-28-VALIDATION.html).

**Defendido:**
- Intercambio en caliente del Nano por una unidad hostil (sin clave → todas
  las tramas fallan el MAC).
- Proceso local que inyecta respuestas de coincidencia falsas en `/dev/r503`.
  Dos capas: el nodo de dispositivo es `root:root 0600` (regla de udev) y el
  demonio lo mantiene con `TIOCEXCL`, por lo que un proceso no root no puede
  abrirlo — e incluso si pudiera, no tiene clave, por lo que la trama falla la
  verificación MAC.
- Replay de tramas `OK match=...` grabadas en una sesión futura.
- Manipulación por volteo de bits de cualquier campo de la trama (comparación
  MAC de tiempo constante).
- Bloqueo (brick) por agotamiento del contador: un peer (o un MITM de una
  sola vez durante `--resync`) que lleve el contador monotónico a `u64::MAX` y
  atasque permanentemente el canal es bloqueado por un techo de contador
  reservado aplicado en ambos extremos (`fw=1.1+`; SPEC §13.4 / auditoría de
  2026-05-28 DoS-2).
- Denegación de servicio del sensor por parte de un usuario local: una única
  compuerta de ranura de captura limita el trabajo de enroll/verificación en
  curso y las rutas de borrado están controladas por acción, por lo que una
  inundación de `Start`/`Stop` (o de borrados concurrentes) no puede atascar la
  autenticación.
- Plantado / borrado / enumeración de huellas entre usuarios por parte de un
  usuario local no root (p. ej., `mallory` llamando a `Claim "root"` y luego
  inscribiendo su propio dedo) — la identidad del llamante se comprueba en cada
  método D-Bus que toma `username`, y la política del bus del sistema deniega
  a los llamantes que no son de `wheel` en la capa de broker.
- **Ataques fuera de línea al disco contra la clave del host** *cuando se
  combina con `--seal-tpm`*: la clave en disco está sellada con TPM2 a PCR7,
  por lo que un `dd` de una partición desmontada o el traslado de un SSD a un
  host hostil produce solo texto cifrado. Solo se desenvuelve en la misma
  máquina bajo la misma política de Secure Boot. Ver [SPEC §13.12](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md).

**No defendido:**
- Compromiso de root del host (la clave está en `/var/lib/r503d/key`,
  `0600 root:root`). El root en un host en ejecución también puede desellar la
  variante sellada por TPM — el sellado atenúa los ataques *fuera de línea*,
  no los en línea.
- Ataque físico al Nano (lectura de EEPROM ~30 s con ISP; decapado de chip;
  etc.).
- Ataque de reflash de firmware (el bootloader de Arduino no tiene firma —
  pero el re-parejado requiere root en el host, por lo que un Nano reflasheado
  no puede ser aceptado como confiable sin comprometer el host de todos modos).
- Compromiso del lado R503 (el protocolo R30x no tiene autenticación en
  absoluto; fuera de nuestro alcance).
- **Postura criptográfica.** MAC SipHash-2-4, clave compartida de 128 bits,
  salida MAC de 64 bits, entradas MAC separadas por dominio. Dos
  implementaciones independientes (C++ artesanal en el AVR con autoprueba KAT
  en el arranque; Rust artesanal en el host, validado cruzadamente bit a bit
  contra el crate de terceros `siphasher` en 1024 vectores aleatorios en CI).
  La comparación MAC del host usa `subtle::ConstantTimeEq`. Los parsers de
  línea se someten a fuzzing de propiedades en cada ejecución de CI
  (~135 000 entradas). `cargo audit` limpio. Clave SipHash envuelta en
  `zeroize::Zeroizing<...>` para que se borre al hacer drop (al igual que los
  búferes de entrada MAC por trama). Un objetivo libFuzzer de `cargo fuzz` se
  incluye en `pcside/daemon/fuzz/` para ejecuciones de corpus largo en
  nightly. Sin auditoría humana externa de pago — eso seguiría siendo valioso,
  PRs bienvenidos.

Modelo de amenazas completo con justificación: [`SPEC.md` §13.1](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md).

## Limitaciones

- **El modo multiusuario funciona, pero solo para miembros de `wheel`.**
  La identidad del llamante se comprueba en cada método D-Bus que toma un
  `username` (`Claim`, `EnrollStart`, `VerifyStart`, `ListEnrolledFingers`,
  `DeleteEnrolledFingers`); las autosolicitudes y `uid 0` (PAM) tienen éxito
  silenciosamente, el acceso entre usuarios desde un llamante no root se
  deniega con `net.reactivated.Fprint.Error.PermissionDenied`. La política del
  bus del sistema restringe aún más qué cuentas pueden siquiera iniciar una
  conversación: solo `root` y los miembros de `wheel` llegan al demonio, todos
  los demás reciben `org.freedesktop.DBus.Error.AccessDenied` en la capa de
  broker. ¿Necesitas realizar enroll entre usuarios? Hazte root:
  `sudo fprintd-enroll target-user`. ¿Necesitas relajar la restricción de
  cruce de usuarios para un kiosco / laboratorio multiusuario? Coloca una
  regla JS en `/etc/polkit-1/rules.d/` dirigida a
  [`net.reactivated.fprint.device.setusername`](https://gitlab.freedesktop.org/libfprint/fprintd/-/blob/master/src/net.reactivated.fprint.device.policy.in)
  — el nombre de la acción replica exactamente el de fprintd upstream.
- **Un solo lector.** El demonio expone un único objeto Device en D-Bus.
  Las configuraciones con varios lectores necesitan una extensión del Manager.
- **Sin emisión de `PropertiesChanged`** para las propiedades de sugerencia
  `finger-present` / `finger-needed`. Todos los clientes fprintd comunes (PAM,
  KDE Settings, GNOME) se basan en las señales `EnrollStatus` / `VerifyStatus`
  (que sí se emiten), no en esas sugerencias por sondeo — pero un cliente
  estricto que haga `Get + PropertiesChanged` verá valores obsoletos.
- **Un solo Nano = un solo punto de fallo.** Si el Nano muere, el inicio de
  sesión por huella desaparece hasta que reflashes un repuesto y lo vuelves a
  emparejar. Mantén un método de autenticación por contraseña habilitado como
  respaldo.
- **La pérdida de State.json se recupera con un solo comando.** Si
  `state.json` se pierde mientras el firmware aún tiene un `last_seen` alto,
  el demonio se topa con `ERR replay` en el primer envío. Ejecuta
  `sudo r503d --resync` para leer el contador del Nano y realinear el host —
  sin necesidad de volver a emparejar. Ver [`SPEC.md` §13.11](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md).

## Solución de problemas```bash
# Daemon logs:
sudo journalctl -u r503d.service -f

# Confirm the sensor enumerates correctly:
ls -l /dev/r503
busctl --system call net.reactivated.Fprint /net/reactivated/Fprint/Device/0 \
    net.reactivated.Fprint.Device ListEnrolledFingers s ""

# Confirm fprintd is masked and r503d owns the bus name:
systemctl is-enabled fprintd  # should print "masked"
busctl --system list | grep -i fprint