KL Security Key

Projeto experimental de engenharia e interoperabilidade de autenticador FIDO2/WebAuthn RP2040 de código aberto da Karaaslan Labs.

Status: projeto de engenharia/pesquisa. Não certificado pela FIDO Alliance. Não é um token de segurança comercial de alta garantia.

O KL Security Key é um derivado curado do polhenarejos/pico-fido. Ele explora até onde uma placa RP2040 de baixo custo pode ser levada como autenticador WebAuthn físico, mantendo identidade, atestação, evidências de validação e limites de confiança explícitos.

Visão geral

Área	Referência de engenharia atual
Hardware	Placa de desenvolvimento USB RP2040
Transporte	USB FIDO HID
Versões CTAP/GetInfo	FIDO_2_0, FIDO_2_1, FIDO_2_3
Presença / verificação do usuário	Botão físico + suporte a PIN/UV
Atestação	Packed ES256, x5c, certificado específico do dispositivo
AAGUID	d9359dc7-6938-5822-b951-006507247d8f
Interoperabilidade	Windows WebAuthn + validação Microsoft Entra local ao tenant
Distribuição	Foco no código-fonte; sem release de binário de firmware KL
Elemento seguro	Nenhum
Certificação	Não certificado pela FIDO Alliance

Por que este projeto existe

O projeto começou com uma pergunta prática: uma placa de desenvolvimento barata pode se tornar uma chave de segurança física utilizável para login WebAuthn real, sem esconder os compromissos de engenharia?

O trabalho interessante acabou não sendo simplesmente fazer o RP2040 rodar FIDO2. As partes mais difíceis foram a identidade do autenticador, a presença física do usuário, a atestação, o comportamento do Windows, mudanças reproduzíveis no código-fonte, a interoperabilidade com a relying party e saber exatamente o que as evidências provam — e o que não provam.

Verificado na referência física

• Registro WebAuthn novo: PASS.
• Autenticação / GetAssertion com a mesma credencial: PASS.
• Provedor do Windows: MicrosoftCtapHidProvider.
• Caminho CTAP2 observado com U2fProtocol=false.
• Presença física do usuário exigida para registro e login.
• Caminho de PIN/verificação do usuário validado.
• Assinatura de atestação packed: PASS.
• Verificação da folha de atestação → KL Security Key Root CA: PASS.
• Concordância do AAGUID entre os dados do autenticador e a extensão do certificado: PASS.
• Registro vinculado ao dispositivo local ao tenant do Microsoft Entra e login físico novo com chave: PASS com a aplicação de atestação desabilitada.

O resultado do Entra é um resultado de interoperabilidade, não uma certificação Microsoft nem reconhecimento global do autenticador. Consulte docs/interoperability-case-study.md para o limite exato.

Arquitetura

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

O runtime validado é intencionalmente restrito: FIDO HID é a interface da chave de segurança; interfaces de runtime não relacionadas no estilo teclado/CCID não fazem parte do perfil de referência KL.

Compilar o perfil de referência

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

A compilação habilita a aplicação da presença física do usuário, o perfil de runtime somente FIDO e o caminho de atestação packed. Material válido de chave/certificado de atestação deve ser provisionado separadamente; chaves privadas de atestação não são publicadas nem provisionadas automaticamente por este repositório.

Limites de confiança e não alegações

Este repositório não alega:

• certificação da FIDO Alliance;
• proteção em nível de elemento seguro contra extração física da chave;
• confiança universal da relying party, allowlisting ou compatibilidade;
• equivalência ao YubiKey, Nitrokey ou outro fornecedor comercial de chave de segurança;
• propriedade da Karaaslan Labs sobre o VID/PID USB do upstream/projeto;
• certificação Microsoft ou reconhecimento global de fornecedor;
• que o sucesso em nível de protocolo com uma relying party prove aceitação por outra.

Leia THREAT-MODEL.md antes de tratar a referência como algo além de um autenticador de engenharia/pesquisa.

Mapa da documentação

Documento	Propósito
docs/architecture.md	Perfil de runtime, layout do código-fonte e limites de engenharia
docs/attestation-and-pki.md	AAGUID, atestação packed e modelo de PKI
docs/validation-evidence.md	Evidências de validação da referência física e do código-fonte curado
docs/interoperability-case-study.md	Evidências e limites de interoperabilidade com relying party / Microsoft Entra
docs/windows-webauthn-debugging.md	Fluxo de depuração Windows/WebAuthn orientado por evidências
THREAT-MODEL.md	Modelo de ameaças e não alegações de segurança
UPSTREAM.md	Proveniência do upstream e mudanças derivadas
SECURITY.md	Relato de vulnerabilidades e política de segurança

Código-fonte, proveniência e modelo de publicação

O submódulo pico-keys-sdk está fixado em um commit conhecido do upstream. Mudanças específicas do KL no SDK são aplicadas por scripts/apply-sdk-overlay.py, que é fixado por commit exato e falha de forma segura em estado inesperado do código-fonte.

Este repositório público é intencionalmente curado em torno do caminho de referência do KL Security Key. Artefatos de pesquisa herdados não relacionados e auxiliares de release legados não fazem parte da superfície publicada do KL; a proveniência do upstream permanece documentada em UPSTREAM.md e no histórico do Git.

A distribuição de binários intencionalmente não é o alvo inicial de publicação enquanto os requisitos de identidade/distribuição USB permanecerem não resolvidos. Código-fonte, documentação e metodologia de validação são os artefatos primários.

O certificado raiz público de atestação está disponível em certs/KL-Security-Key-Root-CA-v1.cert.pem. Chaves privadas de raiz/dispositivo nunca são publicadas.

Contribuição e segurança