## なぜ

Linux向けのハードウェアUSB指紋リーダーは希少で高価であり、既存のもの（Validity、Synapticsなど）は、ベンダーのファームウェア更新で壊れる不安定なlibfprintドライバーを通じてリバースエンジニアリングされています。Grow R503のプロトコルは**公開**されており、Arduino側は自作のコードで、libfprint互換レイヤーは単なるD-Busです。

さらに、ソースを上から下まで読める指紋リーダーが手に入ります。

## 部品リスト

| 部品 | メモ | 参考価格 |
|------|-------|------|
| Grow R503 静電容量式指紋センサー | RGBリング付きの丸型 | 約$10 |
| Arduino Uno R3 / Nano / Mega / 任意のATmega328ボード | SoftwareSerialが動作するもの | $5–$25 |
| ジャンパーワイヤー4〜6本 | Dupont / ブレッドボード | 些細なもの |

これだけです。**レベルシフターも分圧器も不要** — その理由は [`SPEC.md` §3.1](https://github.com/matpb/linux-fingerprint-r503/blob/main/SPEC.md) を参照（R503のRXラインは実際には5Vトレラントで、データシートは嘘をついています）。```
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)

両方が成功した場合、ホストはシールドキーパスを使用できます。`/dev/tpmrm0` が
ない場合 (古いハードウェア、BIOSでTPMが無効、または仮想TPMを持たないVM)、
デフォルトの平文キーフローを使用してください。

## ビルドとインストール

### 1. ファームウェアを書き込む

Arduino IDE で `firmware/r503fp/r503fp.ino` を開き、アップロードします。または
`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. インストール```bash
sudo bash pcside/daemon/dist/install.sh

I notice you've provided instructions but the actual content to translate appears to be missing after "INPUT:".

Could you please provide the chunk content you'd like me to translate? I'm ready to translate it to Japanese (ja) following your rules once the source text is provided.```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)

INPUTに翻訳対象のコンテンツが含まれていません。翻訳するテキストが提供されていないため、このチャンクの翻訳を実行できません。正しい「INPUT:」セクションを再送信してください。```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)

KDE Settings（Plasma 6）とGNOME Control Centerのユーザーアカウント指紋ダイアログは、どちらも上流の`fprintd`を操作するのとまったく同じように`r503d`を操作します。

### 再ペアリング / 鍵のローテーション

新しい鍵を必要とする場合（鍵の漏洩、ハードウェア交換の予定、パラノイア）：```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

このスクリプトは`r503d`を停止し、`firmware/r503fp_wipe/`を再フラッシュしてNano EEPROMを消去し、メインファームウェアを再フラッシュして、`/etc/r503d/allow-pair`を作成し、`r503d --reseal-tpm`を実行して*現在の*PCR7にシールされた新しい鍵を生成し、デーモンを再起動します。実時間：約90秒。登録済みの指紋は保持されます — テンプレートはR503センサーのフラッシュに保存されており、Nanoには保存されません。

スクリプトでは`arduino-cli`が利用可能である必要があります。ユーザーの`$HOME/.local/bin`にインストールされている場合、`$SUDO_USER`経由で自動検出されます。それ以外の場合は、実行前に`ARDUINO_CLI=/full/path/to/arduino-cli`を設定してください。

### 復旧：`state.json`の紛失（カウンターのデシンク）

ホスト鍵が無傷でも`/var/lib/r503d/state.json`が消失しているか、ロールバックされている場合（古いバックアップを復元した、誤ってrmした）、デーモンのカウンターがNanoの`last_seen`より遅れ、フレーム化されたすべてのコマンドが`ERR replay`ではじかれます。`r503d --status`でこの状態が示されます。修正は1つのコマンドだけです：```bash
sudo systemctl stop r503d
sudo r503d --resync                         # reads Nano last_seen, sets host counter to last_seen+1
sudo systemctl start r503d

`sudo arduino-cli` が command-not-found と表示される場合（arduino-cli は `~/.local/bin` にあり、root の `PATH` には含まれていません）、`sudo env "PATH=$PATH" arduino-cli …` のように実行するか、絶対パスを指定してください。

これは攻撃者が利用できるバックドアではありません。再ペアリングにはホスト側での root 権限が必要であり（オプトインファイルと `--pair` CLI の両方に root が必要）、そのため、あなたがすでに root でない限り、書き換えられた Nano を信頼対象にすることはできません。

### アンインストール```bash
sudo bash pcside/daemon/dist/uninstall.sh

## セキュリティモデル — 概要

ワイヤーレベルの認証が対象とする脅威は、
**「5分と予備のNanoを持った邪悪なメイド」** と、`/dev/r503` 上の悪意あるローカルプロセスの組み合わせです。
国家レベルの攻撃者や、ラボを持つハードウェア攻撃者は対象外です。シングルユーザーのデスクトップ展開を想定し、スコープ外リストを文書化しています。
完全な脅威モデルは [`SPEC.md` §13.1](https://github.com/matpb/linux-fingerprint-r503/blob/main/SPEC.md) にあり、実装・レビューの証跡は
[`docs/REVIEW-2026-05-28.md`](https://github.com/matpb/linux-fingerprint-r503/blob/main/docs/REVIEW-2026-05-28.md) にあります。別途実施した
敵対的権限昇格監査（2026-05-28）と、その主張ごとの検証・是正パスは
[`docs/SECURITY-AUDIT-2026-05-28.html`](https://github.com/matpb/linux-fingerprint-r503/blob/main/docs/SECURITY-AUDIT-2026-05-28.html)
および
[`docs/SECURITY-AUDIT-2026-05-28-VALIDATION.html`](https://github.com/matpb/linux-fingerprint-r503/blob/main/docs/SECURITY-AUDIT-2026-05-28-VALIDATION.html)
にあります。

**防御対象:**
- Nanoの悪意あるユニットへのホットスワップ（鍵がない → すべてのフレームがMAC検証に失敗）。
- `/dev/r503` に偽のマッチ応答を注入するローカルプロセス。2層で防御:
  デバイスノードは `root:root 0600`（udevルール）で、デーモンは `TIOCEXCL` で保持するため、
  非rootプロセスはオープンできません。たとえオープンできたとしても鍵がないため、フレームはMAC検証に失敗します。
- 将来のセッションで記録された `OK match=...` フレームのリプレイ。
- 任意のフレームフィールドへのビット反転改ざん（定数時間MAC比較）。
- カウンタ枯渇による破壊: `--resync` 中のワンショットMITMやピアが単調カウンタを `u64::MAX` まで進め、
  チャネルを恒久的に不能にする攻撃は、両端で強制される予約済みカウンタ上限（`fw=1.1+`; SPEC §13.4 / 2026-05-28監査 DoS-2）で阻止されます。
- ローカルユーザーによるセンサーへのDoS: 単一のキャプチャスロットゲートが進行中のエンロール/検証処理を制限し、
  削除パスはアクションゲート付きのため、`Start`/`Stop`（または同時削除）の flood で認証を妨害できません。
- ローカルの非rootユーザーによるクロスユーザー指紋の登録・消去・列挙
  （例: `mallory` が `Claim "root"` を呼び出して自分の指を登録する）— `username` を取るすべてのD-Busメソッドで
  呼び出し元の身元を確認し、システムバスポリシーはブローカー層で非 `wheel` 呼び出し元を拒否します。
- **`--seal-tpm` と併用した場合のホスト鍵へのオフライン・ディスク攻撃**:
  ディスク上の鍵はPCR7にTPM2シールされているため、アンマウントされたパーティションの `dd` や、
  敵対的ホストへのSSDの差し替えでは暗号文しか得られません。
  同じマシン、同じSecure Bootポリシーの下でのみアンシールされます。
  [SPEC §13.12](https://github.com/matpb/linux-fingerprint-r503/blob/main/SPEC.md) を参照。

**防御対象外:**
- ホストのroot権限侵害（鍵は `/var/lib/r503d/key` にあり、`0600 root:root`）。
  稼働中のホストのrootはTPMシール版の鍵もアンシールできます — シールは *オフライン* 攻撃を鈍らせるだけで、オンライン攻撃は防ぎません。
- Nanoへの物理攻撃（ISPによるEEPROM読み出し約30秒、チップのデキャップ等）。
- ファームウェア再書き込み攻撃（Arduinoブートローダーは署名なし — ただし再ペアリングにはホストのroot権限が必要なため、
  ホストが侵害されない限り、再書き込みされたNanoを信頼状態に持ち込むことはできません）。
- R503側の侵害（R30xプロトコルには認証が一切なく、スコープ外）。
- **暗号ポスチャ。** SipHash-2-4 MAC、128ビット共有鍵、64ビットMAC出力、ドメイン分離されたMAC入力。
  2つの独立した実装（AVR上の手書きC++で起動時KAT自己テスト付き、ホスト上の手書きRustでCIで1024のランダムベクトルに対し
  サードパーティ製 `siphasher` クレートとビット単位で相互検証）。ホストのMAC比較は
  `subtle::ConstantTimeEq` を使用。ワイヤーパーサーはCI実行ごとにプロパティファジング（約135,000入力）。
  `cargo audit` クリーン。SipHash鍵は `zeroize::Zeroizing<...>` でラップされ、ドロップ時に消去されます
  （フレームごとのMAC入力バッファも同様）。`cargo fuzz`
  libFuzzerターゲットは `pcside/daemon/fuzz/` に同梱され、nightlyでの長期コーパス実行に対応。
  有料の第三者による人による監査は未実施 — それがあれば有用です。PR歓迎。

根拠付きの完全な脅威モデル: [`SPEC.md` §13.1](https://github.com/matpb/linux-fingerprint-r503/blob/main/SPEC.md)。

## 制限事項

- **マルチユーザーは機能しますが、`wheel` メンバーのみ対象です。** 呼び出し元の身元は
  `username` を取るすべてのD-Busメソッド（`Claim`、`EnrollStart`、`VerifyStart`、`ListEnrolledFingers`、
  `DeleteEnrolledFingers`）で確認され、自己リクエストと `uid 0`（PAM）は黙って成功し、
  非root呼び出し元からのクロスユーザー操作は `net.reactivated.Fprint.Error.PermissionDenied` で拒否されます。
  システムバスポリシーは、会話を開始できるアカウントをさらに制限します:
  `root` と `wheel` メンバーのみがデーモンに到達でき、それ以外はブローカー層で
  `org.freedesktop.DBus.Error.AccessDenied` を受け取ります。
  クロスユーザーのエンロールが必要ですか? rootになります: `sudo fprintd-enroll target-user`。
  キオスク/マルチユーザーラボ向けにクロスユーザーゲートを緩めたいですか?
  `/etc/polkit-1/rules.d/` にJSルールを置き、
  [`net.reactivated.fprint.device.setusername`](https://gitlab.freedesktop.org/libfprint/fprintd/-/blob/master/src/net.reactivated.fprint.device.policy.in)
  を対象にしてください — アクション名は上流のfprintdと完全に同じです。
- **リーダーは1つ。** デーモンはD-Bus上に単一のDeviceオブジェクトを公開します。
  複数リーダー構成にはManagerの拡張が必要です。
- **`finger-present` / `finger-needed` ヒントプロパティの `PropertiesChanged` 発行なし。**
  一般的なfprintdクライアント（PAM、KDE設定、GNOME）はすべて、ポーリング型のヒントではなく
  `EnrollStatus` / `VerifyStatus` シグナル（発行されます）で動作します — しかし
  `Get + PropertiesChanged` を行う厳密なクライアントは古い値を見ることになります。
- **単一Nano = 単一障害点。** Nanoが死ぬと、予備を再フラッシュして再ペアリングするまで指紋ログインは使えません。
  パスワード認証をバックアップとして有効にしておいてください。
- **State.jsonの喪失は1コマンドで復旧可能。** ファームウェアがまだ高い `last_seen` を持っている間に `state.json` が失われると、
  デーモンは最初の送信で `ERR replay` に達します。`sudo r503d --resync` を実行してNanoのカウンタを読み取り、
  ホストを再調整してください — 再ペアリングは不要です。[`SPEC.md` §13.11](https://github.com/matpb/linux-fingerprint-r503/blob/main/SPEC.md) を参照。

## トラブルシューティング```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