KL Security Key

Progetto sperimentale open-source di ingegneria e interoperabilità per un autenticatore FIDO2/WebAuthn basato su RP2040, a cura di Karaaslan Labs.

Stato: progetto di ingegneria/ricerca. Non certificato FIDO Alliance. Non è un token di sicurezza commerciale ad alta affidabilità.

KL Security Key è un derivato curato di polhenarejos/pico-fido. Esplora fin dove può spingersi una scheda RP2040 a basso costo come autenticatore WebAuthn fisico, mantenendo espliciti identità, attestazione, evidenze di validazione e confini di fiducia.

In sintesi

Area	Riferimento ingegneristico attuale
Hardware	Scheda di sviluppo USB RP2040
Trasporto	USB FIDO HID
Versioni CTAP/GetInfo	FIDO_2_0, FIDO_2_1, FIDO_2_3
Presenza / verifica utente	Pulsante fisico + supporto PIN/UV
Attestazione	Packed ES256, x5c, certificato specifico del dispositivo
AAGUID	d9359dc7-6938-5822-b951-006507247d8f
Interoperabilità	Windows WebAuthn + validazione Microsoft Entra locale al tenant
Distribuzione	Source-first; nessuna release binaria del firmware KL
Secure element	Nessuno
Certificazione	Non certificato FIDO Alliance

Perché esiste questo progetto

Il progetto è nato da una domanda pratica: una scheda di sviluppo economica può diventare una chiave di sicurezza fisica utilizzabile per un vero accesso WebAuthn, senza nascondere i compromessi ingegneristici?

Il lavoro interessante si è rivelato non semplicemente far girare FIDO2 su RP2040. Le parti più difficili sono state l'identità dell'autenticatore, la presenza fisica dell'utente, l'attestazione, il comportamento di Windows, modifiche al sorgente riproducibili, l'interoperabilità con le relying party e il sapere esattamente cosa le evidenze dimostrano — e cosa non dimostrano.

Verificato sul riferimento fisico

• Registrazione WebAuthn da zero: PASS.
• Autenticazione / GetAssertion con la stessa credenziale: PASS.
• Provider Windows: MicrosoftCtapHidProvider.
• Percorso CTAP2 osservato con U2fProtocol=false.
• Presenza fisica dell'utente richiesta per registrazione e accesso.
• Percorso PIN/verifica utente validato.
• Firma di attestazione packed: PASS.
• Verifica foglia di attestazione → KL Security Key Root CA: PASS.
• Corrispondenza AAGUID tra authenticator data ed estensione del certificato: PASS.
• Registrazione device-bound locale al tenant Microsoft Entra e accesso fisico da zero con chiave: PASS con applicazione dell'attestazione disabilitata.

Il risultato Entra è un risultato di interoperabilità, non una certificazione Microsoft né un riconoscimento globale dell'autenticatore. Consultare docs/interoperability-case-study.md per il confine esatto.

Architettura

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"]

Il runtime validato è intenzionalmente ristretto: FIDO HID è l'interfaccia della chiave di sicurezza; le interfacce runtime non correlate in stile tastiera/CCID non fanno parte del profilo di riferimento KL.

Compilare il profilo di riferimento

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

La build abilita l'applicazione della presenza fisica dell'utente, il profilo runtime solo FIDO e il percorso di attestazione packed. Materiale valido di chiave/certificato di attestazione deve essere provisionato separatamente; le chiavi private di attestazione non vengono pubblicate né provisionate automaticamente da questo repository.

Confini di fiducia e non-dichiarazioni

Questo repository non dichiara:

• la certificazione FIDO Alliance;
• una protezione a livello di secure element contro l'estrazione fisica della chiave;
• fiducia universale delle relying party, allowlisting o compatibilità;
• equivalenza con YubiKey, Nitrokey o un altro fornitore commerciale di chiavi di sicurezza;
• la proprietà da parte di Karaaslan Labs del VID/PID USB upstream/del progetto;
• la certificazione Microsoft o il riconoscimento globale da parte di vendor;
• che il successo a livello di protocollo con una relying party dimostri l'accettazione da parte di un'altra.

Leggere THREAT-MODEL.md prima di considerare il riferimento come qualcosa di diverso da un autenticatore di ingegneria/ricerca.

Mappa della documentazione

Documento	Scopo
docs/architecture.md	Profilo runtime, struttura del sorgente e confini ingegneristici
docs/attestation-and-pki.md	AAGUID, attestazione packed e modello PKI
docs/validation-evidence.md	Evidenze di validazione del riferimento fisico e del sorgente curato
docs/interoperability-case-study.md	Evidenze e limiti di interoperabilità con relying party / Microsoft Entra
docs/windows-webauthn-debugging.md	Flusso di debug Windows/WebAuthn guidato dalle evidenze
THREAT-MODEL.md	Modello di minaccia e non-dichiarazioni di sicurezza
UPSTREAM.md	Provenienza upstream e modifiche derivate
SECURITY.md	Segnalazione di vulnerabilità e politica di sicurezza

Sorgente, provenienza e modello di pubblicazione

Il submodule pico-keys-sdk è fissato a un commit upstream noto. Le modifiche KL-specifiche all'SDK vengono applicate da scripts/apply-sdk-overlay.py, che è fissato a un commit esatto e fallisce in modo sicuro su stati del sorgente inattesi.

Questo repository pubblico è intenzionalmente curato attorno al percorso di riferimento KL Security Key. Artefatti di ricerca ereditati non correlati e helper di release legacy non fanno parte della superficie KL pubblicata; la provenienza upstream resta documentata in UPSTREAM.md e nella cronologia Git.

La distribuzione binaria non è intenzionalmente l'obiettivo di pubblicazione iniziale finché i requisiti di identità/distribuzione USB restano irrisolti. Sorgente, documentazione e metodologia di validazione sono gli artefatti primari.

Il certificato root pubblico di attestazione è disponibile in certs/KL-Security-Key-Root-CA-v1.cert.pem. Le chiavi private root/device non vengono mai pubblicate.

Contribuire e sicurezza