karaaslanlabs/kl-security-keypacked attestation과 문서화된 Windows/Entra 상호운용성을 갖춘 실험적 RP2040 FIDO2/WebAuthn 인증기
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 FIDO 이슈 #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로 CTAP2 경로 확인됨.Entra 결과는 상호운용성 결과이며, Microsoft 인증이나 전역 인증자 인정이 아닙니다. 정확한 경계는 docs/interoperability-case-study.md를 참조하십시오.
현재의 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 전용 런타임 프로필 및 packed-attestation 경로를 활성화하며, 병합되지 않은 v5.3 변경 사항의 빌드가 아닙니다. 유효한 attestation 키/인증서 자료는 별도로 프로비저닝해야 하며, 개인 attestation 키는 이 저장소에서 게시되거나 자동 프로비저닝되지 않습니다. UF2를 빌드한다고 해서 기기에 플래싱할 권한이 부여되는 것은 아닙니다.
이 저장소는 다음을 주장하지 않습니다:
이 참조 구현을 엔지니어링/연구용 인증기 이상으로 취급하기 전에 THREAT-MODEL.md를 읽으십시오.
| 문서 | 목적 |
|---|---|
docs/architecture.md | 런타임 프로필, 소스 레이아웃 및 엔지니어링 경계 |
docs/attestation-and-pki.md | AAGUID, packed attestation 및 PKI 모델 |
docs/validation-evidence.md | 물리적 참조 및 선별된 소스 검증 증거 |
docs/interoperability-case-study.md | Relying party / 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에 의해 적용되며, 이 스크립트는 정확한 커밋에 고정되어 있고 예상치 못한 소스 상태에서는 fail-closed 방식으로 동작합니다.
이 공개 저장소는 의도적으로 KL Security Key 참조 경로를 중심으로 선별되었습니다. 무관한 상속된 연구 산출물 및 레거시 릴리스 헬퍼는 게시된 KL 표면의 일부가 아니며, 업스트림 출처는 UPSTREAM.md 및 Git 이력에 계속 문서화되어 있습니다.
USB 아이덴티티/배포 요구 사항이 미해결 상태인 동안 바이너리 배포는 의도적으로 초기 게시 대상이 아닙니다. 소스, 문서 및 검증 방법론이 주요 산출물입니다.
공개 attestation 루트 인증서는 certs/KL-Security-Key-Root-CA-v1.cert.pem에서 확인할 수 있습니다. 개인 루트/기기 키는 절대 게시되지 않습니다.
기여는 작고, 감사 가능하며, 보안 영향에 대해 명시적인 경우 환영합니다. CONTRIBUTING.md부터 시작하십시오. 패치되지 않은 취약점에 대해서는 공개 이슈를 열지 마십시오; SECURITY.md를 따르십시오.
KL Security Key는 polhenarejos/pico-fido에서 파생되었으며 polhenarejos/pico-keys-sdk를 사용합니다. 소스는 GNU Affero General Public License v3.0에 따라 유지됩니다; LICENSE, NOTICE.md 및 UPSTREAM.md를 참조하십시오.