TheMaxMur/RS-Key
GitHub: TheMaxMur/RS-Key
RS-Key 是一款用 Rust 编写的 RP2350 开源安全密钥固件，可将开发板变为支持 FIDO2、OpenPGP、PIV、OATH 等多种协议的 USB 认证器。
Stars: 34 | Forks: 5
# RS-Key
[](https://github.com/TheMaxMur/RS-Key/actions/workflows/ci.yml)
[](https://github.com/TheMaxMur/RS-Key/actions/workflows/deep-checks.yml)
[](https://themaxmur.github.io/RS-Key/)
RS-Key (RSK，*Raspberry Security Key* —— 也是对它使用 Rust 编写的一种致意)
是为 Raspberry Pi **RP2350** 开发的开源安全密钥固件。它可以使
RP2350 开发板表现得像一个 USB 认证器，并提供了用于驱动它的主机工具。它使用 Rust（`no_std`，[embassy](https://embassy.dev)）编写，旨在用于开发、研究和受控实验 —— **而不是**经过审计的商业密钥的直接替代品。
## 项目状态
这是一个可用的、由单人维护的业余项目，目前正在积极开发中。第一个
标记的发布版本是 **v0.1.0**；日常支持的版本是
`main` 的最新提交，每次行为变更都会递增 USB `bcdDevice` 构建计数器，以便可以精确地命名构建版本。大部分协议接口已针对真实的主机软件进行了测试；实际在硬件上检查过的内容（带有日期）位于
[docs/interop.md](docs/interop.md) 中。请将该矩阵中未提及的任何内容视为未经验证。
## 文档
文档位于 [docs/](docs/) 中，并已作为网站发布：
**
browser · ssh · gpg · ykman · rsk / rsk-tui"] host -->|USB| usb["Composite USB device"] usb --> fido["FIDO HID"] usb --> ccid["CCID (smart-card)"] usb --> kbd["Keyboard (OTP typing)"] fido & ccid & kbd --> applets["Applets: FIDO2/U2F · OpenPGP · PIV · OATH · OTP · mgmt"] applets --> core["Master seed · TRNG · flash store"] core --> rp["RP2350 (no secure element)"] ``` ## 不能防范的威胁 - **物理 / 实验室攻击** — 除了片上毛刺检测器之外的解封、微探测、故障注入、 功率/电磁侧信道，以及 flash 仿真 TOCTOU。RP2350 不是安全元件；如果您的威胁模型包括资金充足的实验室，请购买经过认证的密钥。 - **设备解锁状态下主机被入侵** — 与任何安全密钥一样，在插入并解锁期间，它将执行您已授权的操作。 - **未进行可选加固时的密钥丢失** — 只有在您烧录 OTP 主密钥（参见下文的生产环境部分）后，静态保护才具有实际意义。 完整的原因分析：[docs/threat-model.md](docs/threat-model.md)。 ## 硬件 任何带有 USB 接口的 RP2350 开发板。在 **Waveshare RP2350-One** 上开发和测试 （GPIO16 上的 WS2812 状态指示灯；没有 LED 的开发板也能正常运行）。不同的 flash 大小或 LED 引脚只需更改一行构建配置。详细信息请见： [docs/hardware.md](docs/hardware.md)。 ## 快速开始 ``` git clone https://github.com/TheMaxMur/RS-Key && cd RS-Key nix develop # toolchain, picotool, host tools — everything cargo build --release -p firmware picotool uf2 convert target/thumbv8m.main-none-eabihf/release/firmware -t elf firmware.uf2 # 按住 BOOTSEL，插入开发板，然后将 image 复制到 RP2350 驱动器： cp firmware.uf2 /Volumes/RP2350/ # macOS; on Linux, the mounted RP2350 mass-storage volume ``` 重新插入开发板，它将枚举为一个复合 USB 认证器。默认的 构建需要**物理触摸**（BOOTSEL 按钮）才能执行 FIDO 操作； 使用 `--no-default-features` 构建可生成免触摸版本（自动化测试 套件需要它）。完整演练请见：[docs/quickstart.md](docs/quickstart.md)。 在 Linux 上，CCID 部分需要进行一些主机设置：[docs/linux.md](docs/linux.md)。 ## 开发环境设置 `nix develop` 包含了所有设置 —— 带有 `thumbv8m.main-none-eabihf` 目标平台的 Rust、`picotool`、Python 主机堆栈以及安全工具。一条命令 即为合并关卡，并且 CI 运行的也是完全相同的脚本： ``` nix develop -c ./scripts/check.sh # fmt, clippy, host tests, firmware builds, audit, deny, gitleaks ``` 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/testing.md](docs/testing.md)。 ## 生产环境 / secure boot（不可逆 —— 请先阅读） 默认情况下，该固件通过拖放方式烧录，并将其静态 加密的根密钥植于设备上派生的密钥中。一个可选的、选择加入的路径加固了 这一点：它将随机主密钥烧录到 RP2350 OTP 中，并启用 secure boot，因此 开发板仅运行您签名的镜像。 ``` flowchart LR subgraph dev["Default (development)"] d1["drag-and-drop UF2"] --> d2["flash-derived key"] --> d3["boots any image"] end subgraph prod["Production (opt-in)"] p1["sign UF2
picotool seal"] --> p2{{"burn OTP fuses
IRREVERSIBLE"}} --> p3["secure boot:
only your signed images"] end ``` 这些步骤会**烧录一次性可编程熔丝**：它们无法撤销，它们 将永远改变您的重新烧录工作流（仅限签名镜像），并且一个失误就可能 导致开发板变砖。但这也正是不法分子窃取开发板后，其 flash 转储数据变得毫无用处的原因。 在执行任何操作之前，请务必从头到尾阅读 [docs/production.md](docs/production.md)。 ## 主机工具 在开发 shell 中，有两个命令位于 `PATH` 中： - **`rsk`** — 设备 CLI（Python）：`rsk status`、`rsk backup`、`rsk lock`、 `rsk secure-boot`、`rsk otp`、`rsk fido`、`rsk led`、`rsk reboot` 等（`rsk --help`） - **`rsk-tui`** — 用于日常读取和一些带内操作的终端仪表板 （[指南](docs/guides/tui.md)；`rsk-tui --demo` 无需硬件） 另外，**`rsk-wipe`** 是一个仅在内存中运行的擦除 flash 的*镜像*，您可以刻意烧录它，以擦除开发板进行全新测试 —— 它的构建和烧录方式类似于固件，而不是从 `PATH` 中运行（[rsk-wipe/README.md](rsk-wipe/README.md)）。 ## 局限性（简表） - **无安全元件。** OTP + secure boot 是真正的加固，但物理 攻击不在范围内。 - **Seed 备份仅覆盖确定性身份** — 常驻 passkeys、 OpenPGP 和 PIV 密钥在更换开发板后无法保留。 - **不支持 Brainpool / X448 / Ed448** OpenPGP 曲线（没有成熟的 `no_std` Rust 实现）。 - 默认的 USB 标识是 **RS-Key 自己的** pid.codes ID `0x1209:0x0001`； `ykman` / Yubico Authenticator 自动识别的 YubiKey USB 标识是 在构建时开启 `VIDPID=Yubikey5` 的版本，请勿用于分发。 详细信息和原因分析：[docs/limitations.md](docs/limitations.md)。 ## 许可证 **AGPL-3.0-only** — 参见 [LICENSE](LICENSE)、[NOTICE](NOTICE) 和 [COMPLIANCE.md](COMPLIANCE.md)。RS-Key 是对 Pol Henarejos 开发的 AGPL-3.0-**only** [pico-keys](https://github.com/polhenarejos) 固件 系列（pico-fido / pico-openpgp / pico-keys-sdk）从零开始的 Rust 重新实现；上游 授权仅限 version-3-only，因此 RS-Key 继承了它，其分支也必须如此。与 Yubico、Nitrokey 或 Raspberry Pi 附属或认可无关。参见[动机](docs/motivation.md)。
browser · ssh · gpg · ykman · rsk / rsk-tui"] host -->|USB| usb["Composite USB device"] usb --> fido["FIDO HID"] usb --> ccid["CCID (smart-card)"] usb --> kbd["Keyboard (OTP typing)"] fido & ccid & kbd --> applets["Applets: FIDO2/U2F · OpenPGP · PIV · OATH · OTP · mgmt"] applets --> core["Master seed · TRNG · flash store"] core --> rp["RP2350 (no secure element)"] ``` ## 不能防范的威胁 - **物理 / 实验室攻击** — 除了片上毛刺检测器之外的解封、微探测、故障注入、 功率/电磁侧信道，以及 flash 仿真 TOCTOU。RP2350 不是安全元件；如果您的威胁模型包括资金充足的实验室，请购买经过认证的密钥。 - **设备解锁状态下主机被入侵** — 与任何安全密钥一样，在插入并解锁期间，它将执行您已授权的操作。 - **未进行可选加固时的密钥丢失** — 只有在您烧录 OTP 主密钥（参见下文的生产环境部分）后，静态保护才具有实际意义。 完整的原因分析：[docs/threat-model.md](docs/threat-model.md)。 ## 硬件 任何带有 USB 接口的 RP2350 开发板。在 **Waveshare RP2350-One** 上开发和测试 （GPIO16 上的 WS2812 状态指示灯；没有 LED 的开发板也能正常运行）。不同的 flash 大小或 LED 引脚只需更改一行构建配置。详细信息请见： [docs/hardware.md](docs/hardware.md)。 ## 快速开始 ``` git clone https://github.com/TheMaxMur/RS-Key && cd RS-Key nix develop # toolchain, picotool, host tools — everything cargo build --release -p firmware picotool uf2 convert target/thumbv8m.main-none-eabihf/release/firmware -t elf firmware.uf2 # 按住 BOOTSEL，插入开发板，然后将 image 复制到 RP2350 驱动器： cp firmware.uf2 /Volumes/RP2350/ # macOS; on Linux, the mounted RP2350 mass-storage volume ``` 重新插入开发板，它将枚举为一个复合 USB 认证器。默认的 构建需要**物理触摸**（BOOTSEL 按钮）才能执行 FIDO 操作； 使用 `--no-default-features` 构建可生成免触摸版本（自动化测试 套件需要它）。完整演练请见：[docs/quickstart.md](docs/quickstart.md)。 在 Linux 上，CCID 部分需要进行一些主机设置：[docs/linux.md](docs/linux.md)。 ## 开发环境设置 `nix develop` 包含了所有设置 —— 带有 `thumbv8m.main-none-eabihf` 目标平台的 Rust、`picotool`、Python 主机堆栈以及安全工具。一条命令 即为合并关卡，并且 CI 运行的也是完全相同的脚本： ``` nix develop -c ./scripts/check.sh # fmt, clippy, host tests, firmware builds, audit, deny, gitleaks ``` 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/testing.md](docs/testing.md)。 ## 生产环境 / secure boot（不可逆 —— 请先阅读） 默认情况下，该固件通过拖放方式烧录，并将其静态 加密的根密钥植于设备上派生的密钥中。一个可选的、选择加入的路径加固了 这一点：它将随机主密钥烧录到 RP2350 OTP 中，并启用 secure boot，因此 开发板仅运行您签名的镜像。 ``` flowchart LR subgraph dev["Default (development)"] d1["drag-and-drop UF2"] --> d2["flash-derived key"] --> d3["boots any image"] end subgraph prod["Production (opt-in)"] p1["sign UF2
picotool seal"] --> p2{{"burn OTP fuses
IRREVERSIBLE"}} --> p3["secure boot:
only your signed images"] end ``` 这些步骤会**烧录一次性可编程熔丝**：它们无法撤销，它们 将永远改变您的重新烧录工作流（仅限签名镜像），并且一个失误就可能 导致开发板变砖。但这也正是不法分子窃取开发板后，其 flash 转储数据变得毫无用处的原因。 在执行任何操作之前，请务必从头到尾阅读 [docs/production.md](docs/production.md)。 ## 主机工具 在开发 shell 中，有两个命令位于 `PATH` 中： - **`rsk`** — 设备 CLI（Python）：`rsk status`、`rsk backup`、`rsk lock`、 `rsk secure-boot`、`rsk otp`、`rsk fido`、`rsk led`、`rsk reboot` 等（`rsk --help`） - **`rsk-tui`** — 用于日常读取和一些带内操作的终端仪表板 （[指南](docs/guides/tui.md)；`rsk-tui --demo` 无需硬件） 另外，**`rsk-wipe`** 是一个仅在内存中运行的擦除 flash 的*镜像*，您可以刻意烧录它，以擦除开发板进行全新测试 —— 它的构建和烧录方式类似于固件，而不是从 `PATH` 中运行（[rsk-wipe/README.md](rsk-wipe/README.md)）。 ## 局限性（简表） - **无安全元件。** OTP + secure boot 是真正的加固，但物理 攻击不在范围内。 - **Seed 备份仅覆盖确定性身份** — 常驻 passkeys、 OpenPGP 和 PIV 密钥在更换开发板后无法保留。 - **不支持 Brainpool / X448 / Ed448** OpenPGP 曲线（没有成熟的 `no_std` Rust 实现）。 - 默认的 USB 标识是 **RS-Key 自己的** pid.codes ID `0x1209:0x0001`； `ykman` / Yubico Authenticator 自动识别的 YubiKey USB 标识是 在构建时开启 `VIDPID=Yubikey5` 的版本，请勿用于分发。 详细信息和原因分析：[docs/limitations.md](docs/limitations.md)。 ## 许可证 **AGPL-3.0-only** — 参见 [LICENSE](LICENSE)、[NOTICE](NOTICE) 和 [COMPLIANCE.md](COMPLIANCE.md)。RS-Key 是对 Pol Henarejos 开发的 AGPL-3.0-**only** [pico-keys](https://github.com/polhenarejos) 固件 系列（pico-fido / pico-openpgp / pico-keys-sdk）从零开始的 Rust 重新实现；上游 授权仅限 version-3-only，因此 RS-Key 继承了它，其分支也必须如此。与 Yubico、Nitrokey 或 Raspberry Pi 附属或认可无关。参见[动机](docs/motivation.md)。
标签：FIDO2, OpenPGP, RP2350, Rust, StruQ, 可视化界面, 固件开发, 安全密钥, 网络流量审计, 逆向工具, 通知系统