由 Karaaslan Labs 开发的实验性开源 RP2040 FIDO2/WebAuthn 认证器工程与互操作性项目。
状态： 工程/研究项目。未获得 FIDO 联盟认证。 并非商用高保障安全令牌。
证据边界： 下文中的真实设备观测结果属于已冻结的 v5.2。v5.3 的加固工作仅在设备外进行，尚未在物理参考设备上安装或验证。
KL Security Key 是 polhenarejos/pico-fido 的精选衍生项目。它探索低成本 RP2040 开发板作为物理 WebAuthn 认证器所能达到的极限，同时明确身份、认证声明、验证证据与信任边界。
| 领域 | 已冻结的 v5.2 物理参考设备 |
|---|---|
| 硬件 | RP2040 USB 开发板 |
| 传输 | USB FIDO HID |
| CTAP/GetInfo 版本 | FIDO_2_0、FIDO_2_1、FIDO_2_3 |
| 用户存在性 / 验证 | 物理按键 + PIN/UV 支持 |
| 认证声明 | Packed ES256、x5c、设备专属证书 |
| AAGUID | d9359dc7-6938-5822-b951-006507247d8f |
| 互操作性 | Windows WebAuthn + 租户本地 Microsoft Entra 验证 |
| 分发 | 源码优先；不发布 KL 固件二进制 |
| 安全元件 | 无 |
| 认证 | 未获得 FIDO 联盟认证 |
main 源码参考构建在 scripts/build-kl-reference.sh 中选择 -DPICO_BOARD=pico，面向配备 2 MiB 外部闪存的 Raspberry Pi Pico 标准开发板配置。独立的 v5.3 设备外构建器同样选择 -DPICO_BOARD=pico；其 UF2 输出校验器 会检查 Pico 的 2 MiB 闪存地址窗口。这些是源码/构建约束，而非对每一块 RP2040 开发板的物理验证。
其他 RP2040 开发板可能具有不同的闪存容量或开发板配置。上游 Pico FIDO issue #278 记录了一块大闪存开发板上首次 WebAuthn 操作失败的情况，原因是固件的编译期闪存限制与其运行时布局不匹配。该上游发现并非 KL Security Key 的复现故障，但它说明了为何仅匹配 RP2040 芯片本身不足以作为兼容性证据。
请勿假定 KL 参考固件可在任意 RP2040 开发板上运行，也不要仅凭构建成功或 UF2 封装有效就向设备烧录固件。此处不主张任何替代开发板的兼容性、新的硬件测试或固件二进制分发。已冻结的 v5.2 物理参考设备未作任何更改。
项目始于一个实际问题：一块廉价的开发板能否成为可用于真实 WebAuthn 登录的物理安全密钥，同时不隐藏工程上的妥协？
有趣的工作最终并非仅仅让 RP2040 运行 FIDO2。更困难的部分在于认证器身份、物理用户存在性、认证声明、Windows 行为、可复现的源码变更、依赖方互操作性，以及确切了解证据能证明什么——以及不能证明什么。
本节结果均使用保留的 v5.2 设备获得，不得归因于后续源码或实验性固件构建。有关冻结的 UF2 SHA-256 与测试边界，请参见 docs/validation-evidence.md。
MicrosoftCtapHidProvider。U2fProtocol=false。Entra 的结果属于互操作性结果，并非 Microsoft 认证或全球认证器认可。确切边界请参见 docs/interoperability-case-study.md。
当前的 HID/APDU/OTP 加固工作记录在 Draft PR #7 中。它包括基于补丁的 SDK 集成路径、主机侧回归测试以及本地隔离 ARM 构建证据。这些检查并非实机测试、完整 FIDO 一致性测试、认证或生产发布。 GitHub Actions 运行主机/源码测试和发布检查；完整的 ARM 构建已在本地验证，而非在 GitHub Actions 中验证。
main 分支及其参考构建不会自动包含未合并的 v5.3 补丁。如需了解当前的实验性证据和未解决的阻塞问题，请使用 PR #7，而不要将历史 UF2 哈希或个别测试通过视为最新的硬件状态。本工作产生的任何固件二进制文件均不提供下载或刷写。
flowchart LR
RP["Relying party / Microsoft Entra"] --> WA["Browser + Windows WebAuthn"]
WA --> CTAP["CTAP2 over USB HID"]
CTAP --> KEY["KL Security Key<br/>RP2040"]
KEY --> AT["Packed ES256 attestation<br/>device-specific key + x5c"]
AT --> ROOT["KL Security Key Root CA"]
经过验证的运行时范围有意保持狭窄：FIDO HID 是安全密钥接口；无关的键盘/CCID 风格运行时接口不属于 KL 参考配置文件。
main 源码参考配置文件git clone --recurse-submodules https://github.com/karaaslanlabs/kl-security-key.git
cd kl-security-key
export PICO_SDK_PATH=/path/to/pico-sdk
export PICO_TOOLCHAIN_PATH=/path/to/arm-none-eabi-toolchain
./scripts/build-kl-reference.sh
main 构建启用了物理用户在场强制、仅 FIDO 运行时配置和打包证明路径；它不是未合并的 v5.3 变更的构建。有效的证明密钥/证书材料必须单独配置；私有证明密钥不会由本仓库发布或自动配置。构建 UF2 并不授权刷写设备。
本仓库不声称：
在将本参考实现视为工程/研究认证器之外的任何事物之前，请先阅读 THREAT-MODEL.md。
| 文档 | 用途 |
|---|---|
docs/architecture.md | 运行时配置、源码布局与工程边界 |
docs/attestation-and-pki.md | AAGUID、打包证明与 PKI 模型 |
docs/validation-evidence.md | 物理参考与精选源码验证证据 |
docs/interoperability-case-study.md | 依赖方 / Microsoft Entra 互操作性证据与局限 |
docs/windows-webauthn-debugging.md | 以证据为导向的 Windows/WebAuthn 调试工作流 |
THREAT-MODEL.md | 威胁模型与安全非声明 |
UPSTREAM.md | 上游来源与衍生变更 |
SECURITY.md | 漏洞报告与安全策略 |
pico-keys-sdk 子模块固定到已知的上游提交。KL 特定的 SDK 变更由 scripts/apply-sdk-overlay.py 应用，该脚本精确固定提交，并在遇到意外源码状态时失败关闭。
本公开仓库有意围绕 KL Security Key 参考路径进行精选。无关的继承研究产物和遗留发布辅助工具不属于已发布的 KL 范围；上游来源仍记录在 UPSTREAM.md 和 Git 历史中。
在 USB 身份/分发要求仍未解决期间，二进制分发有意不作为初始发布目标。源码、文档和验证方法是主要产物。
公开证明根证书位于 certs/KL-Security-Key-Root-CA-v1.cert.pem。私有根/设备密钥永不发布。
欢迎贡献，前提是规模小、可审计且明确说明安全影响。请从 CONTRIBUTING.md 开始。不要为未修补的漏洞提交公开 issue；请遵循 SECURITY.md。
KL Security Key 衍生自 polhenarejos/pico-fido 并使用 polhenarejos/pico-keys-sdk。源码仍遵循 GNU Affero General Public License v3.0；参见 LICENSE、NOTICE.md 和 UPSTREAM.md。
Karaaslan Labs 不声称对上游 Pico FIDO / Pico Keys SDK 工作拥有著作权。原始声明予以保留，KL 特定修改另行记录。
如需有边界的 WebAuthn/passkey 调试或 FIDO2 认证器/证明工程咨询，请联系 [email protected]。
实验性物理 KL Security Key 不出售。
Karaaslan Labs：https://karaaslanlabs.com