KL Security Key

Karaaslan Labsによる実験的なオープンソースRP2040 FIDO2/WebAuthn認証器のエンジニアリングおよび相互運用性プロジェクト。

ステータス: エンジニアリング/研究プロジェクト。FIDO Alliance認証取得済みではありません。 商用の高保証セキュリティトークンではありません。

証拠の境界: 以下の実機での観測結果は凍結された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 Alliance認証取得済みではありません

ボードとフラッシュサイズの範囲

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 FIDOissue #278は、ファームウェアのコンパイル時のフラッシュ制限が実行時のレイアウトと一致しなかった場合に、より大きなフラッシュを搭載したボードで最初のWebAuthn操作が失敗する事例を記録しています。この上流の知見はKL Security Keyで再現された障害ではありませんが、RP2040チップが一致するだけでは互換性の十分な証拠にならない理由を示しています。

KLリファレンスファームウェアが任意のRP2040ボードで動作すると仮定したり、ビルドの成功や有効なUF2フレーミングのみを根拠にデバイスへ書き込んだりしないでください。ここでは代替ボードの互換性、新しいハードウェアテスト、ファームウェアバイナリの配布について一切主張していません。凍結されたv5.2物理リファレンスは変更されていません。

このプロジェクトの存在理由

このプロジェクトは実用的な問いから始まりました。安価な開発ボードは、エンジニアリング上の妥協を隠すことなく、実際のWebAuthnサインインに使える物理セキュリティキーになり得るのか?

興味深い作業は、単にRP2040でFIDO2を動かすことではありませんでした。より難しい部分は、認証器のアイデンティティ、物理的なユーザープレゼンス、アテステーション、Windowsの挙動、再現可能なソース変更、リライングパーティの相互運用性、そして証拠が何を証明し、何を証明しないのかを正確に把握することでした。

凍結されたv5.2物理リファレンスで検証済み

このセクションの結果は保存されたv5.2デバイスで得られたものであり、後のソースや実験的なファームウェアビルドに帰属させてはなりません。凍結されたUF2 SHA-256とテスト境界についてはdocs/validation-evidence.mdを参照してください。

• 新規 WebAuthn 登録: PASS。
• 同じクレデンシャルでの認証 / GetAssertion: PASS。
• Windows プロバイダー: MicrosoftCtapHidProvider。
• U2fProtocol=false で CTAP2 パスを確認。
• 登録とサインインには物理的なユーザー存在が必要。
• PIN/ユーザー検証パスを検証済み。
• Packed アテステーション署名: PASS。
• アテステーションリーフ → KL Security Key Root CA の検証: PASS。
• オーセンティケータデータと証明書拡張間の AAGUID 一致: PASS。
• Microsoft Entra テナントローカルのデバイスバインド登録と新規物理キーによるサインイン: アテステーション強制を無効にして PASS。

Entra の結果は相互運用性の結果であり、Microsoft の認定やグローバルなオーセンティケータ認識ではありません。正確な境界については docs/interoperability-case-study.md を参照してください。

v5.3 開発 — オフデバイスのみ

現在の HID/APDU/OTP ハードニングは Draft PR #7 で追跡されています。これにはパッチベースの SDK 統合パス、ホスト側の回帰テスト、ローカルの分離 ARM ビルドの証拠が含まれます。これらのチェックは実機テスト、完全な FIDO 適合性テスト、認定、または本番リリースではありません。 GitHub Actions はホスト/ソーステストと公開チェックを実行します。完全な ARM ビルドはローカルで検証済みであり、GitHub Actions では検証されていません。

main ブランチとその参照ビルドには、未マージの v5.3 パッチは自動的には含まれません。現在の実験的証拠と未解決のブロッカーについては、過去の UF2 ハッシュや個々のテスト合格を最新のハードウェア状態として扱うのではなく、PR #7 を使用してください。この作業によるファームウェアバイナリはダウンロードや書き込み用に提供されていません。

アーキテクチャ

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 をビルドすることは、デバイスへの書き込みを許可するものではありません。

信頼境界と非主張事項

このリポジトリは以下を主張しません:

• FIDO Alliance の認証;
• 物理的なキー抽出に対するセキュアエレメントレベルの保護;
• 普遍的なリライングパーティの信頼、許可リスト登録、または互換性;
• YubiKey、Nitrokey、その他の商用セキュリティキーベンダーとの同等性;
• アップストリーム/プロジェクトの USB VID/PID に対する Karaaslan Labs の所有権;
• Microsoft の認証またはグローバルなベンダー認知;
• あるリライングパーティとのプロトコルレベルの成功が、別のリライングパーティによる受け入れを証明するということ。

このリファレンスをエンジニアリング/研究用オーセンティケータ以上のものとして扱う前に、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 を参照してください。