KL Security Key

由 Karaaslan Labs 开发的实验性开源 RP2040 FIDO2/WebAuthn 认证器工程与互操作性项目。

状态： 工程/研究项目。未获得 FIDO 联盟认证。 并非商业高保障安全令牌。

KL Security Key 是 polhenarejos/pico-fido 的精选衍生项目。它探索在保持身份、认证、验证证据和信任边界明确的前提下，低成本 RP2040 开发板作为物理 WebAuthn 认证器能够达到的程度。

概览

领域	当前工程参考
硬件	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 联盟认证

项目存在的意义

该项目始于一个实际问题：一块廉价的开发板能否成为用于真实 WebAuthn 登录的可用物理安全密钥，同时不隐藏工程上的妥协？

有趣的工作最终并非仅仅让 RP2040 运行 FIDO2。更困难的部分是认证器身份、物理用户存在、认证、Windows 行为、可复现的源码变更、依赖方互操作性，以及确切了解证据能证明什么——以及不能证明什么。

在物理参考设备上验证

全新 WebAuthn 注册：通过。
使用同一凭据进行认证 / GetAssertion：通过。
Windows 提供程序：MicrosoftCtapHidProvider。
观察到 CTAP2 路径，U2fProtocol=false。
注册和登录均需要物理用户存在。
PIN/用户验证路径已验证。
Packed 认证签名：通过。
认证叶证书 → KL Security Key Root CA 验证：通过。
认证器数据与证书扩展之间的 AAGUID 一致：通过。
Microsoft Entra 租户本地设备绑定注册和全新物理密钥登录：在禁用认证强制的情况下通过。

Entra 结果是互操作性结果，而非 Microsoft 认证或全球认证器认可。确切边界请参见 docs/interoperability-case-study.md。

架构

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 参考配置的一部分。

构建参考配置

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

该构建启用物理用户存在强制、仅 FIDO 运行时配置和 packed 认证路径。有效的认证密钥/证书材料必须单独配置；私有认证密钥不会由本仓库发布或自动配置。

信任边界与非声明

本仓库不声称：

FIDO 联盟认证；
安全元件级别的物理密钥提取防护；
通用依赖方信任、允许列表或兼容性；
与 YubiKey、Nitrokey 或其他商业安全密钥供应商等同；
Karaaslan Labs 拥有上游/项目 USB VID/PID；
Microsoft 认证或全球供应商认可；
与一个依赖方的协议级成功证明会被另一个依赖方接受。

在将参考设备视为工程/研究认证器之外的任何东西之前，请阅读 THREAT-MODEL.md。

文档地图

文档	用途
`docs/architecture.md`	运行时配置、源码布局和工程边界
`docs/attestation-and-pki.md`	AAGUID、packed 认证和 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]。

付费调试服务：https://www.upwork.com/services/product/development-it-get-expert-webauthn-passkey-and-fido2-authentication-debugging-2106330281996723797。该服务涵盖软件/认证工程；物理 KL Security Key 不出售。

Karaaslan Labs：https://karaaslanlabs.com

kl-security-key

最受欢迎