karaaslanlabs/kl-security-keyAutenticador FIDO2/WebAuthn experimental para RP2040 com atestação empacotada e interoperabilidade documentada com Windows/Entra
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.
Limite de evidências: as observações em dispositivo real abaixo pertencem à v5.2 congelada. O trabalho de endurecimento da v5.3 é apenas fora do dispositivo e não foi instalado nem verificado na referência física.
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 explícitos a identidade, a atestação, as evidências de validação e os limites de confiança.
| Área | Referência física v5.2 congelada |
|---|---|
| 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 | WebAuthn do Windows + validação local ao tenant no Microsoft Entra |
| Distribuição | Prioridade ao código-fonte; nenhuma versão de binário de firmware KL |
| Elemento seguro | Nenhum |
| Certificação | Não certificado pela FIDO Alliance |
A compilação de referência do código-fonte em main seleciona -DPICO_BOARD=pico em scripts/build-kl-reference.sh, visando a configuração padrão da placa Raspberry Pi Pico com 2 MiB de flash externa. O construtor isolado fora do dispositivo da v5.3 também seleciona -DPICO_BOARD=pico; seu validador de saída UF2 verifica a janela de endereço de flash de 2 MiB da Pico. Estas são restrições de código-fonte/compilação, não validação física de todas as placas RP2040.
Outras placas RP2040 podem ter capacidade de flash ou configurações de placa diferentes. A issue #278 do Pico FIDO upstream documenta uma falha na primeira operação WebAuthn em uma placa com flash maior quando o limite de flash em tempo de compilação do firmware não correspondia ao seu layout em tempo de execução. Essa descoberta upstream não é uma falha reproduzida do KL Security Key, mas ilustra por que corresponder apenas ao chip RP2040 não é evidência suficiente de compatibilidade.
Não presuma que o firmware de referência KL funciona em placas RP2040 arbitrárias, nem grave um dispositivo apenas com base em uma compilação bem-sucedida ou em um enquadramento UF2 válido. Nenhuma compatibilidade com placas alternativas, novo teste de hardware ou distribuição de binário de firmware é alegada aqui. A referência física v5.2 congelada não foi alterada.
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 executar FIDO2. As partes mais difíceis foram a identidade do autenticador, a presença física do usuário, a atestação, o comportamento no Windows, as mudanças reproduzíveis no código-fonte, a interoperabilidade com relying parties e saber exatamente o que as evidências provam — e o que não provam.
Os resultados nesta seção foram obtidos com o dispositivo v5.2 preservado e não devem ser atribuídos a compilações posteriores de código-fonte ou de firmware experimental. Consulte docs/validation-evidence.md para o SHA-256 do UF2 congelado e os limites dos testes.
MicrosoftCtapHidProvider.U2fProtocol=false.O resultado do Entra é um resultado de interoperabilidade, não uma certificação Microsoft nem um reconhecimento global de autenticador. Consulte docs/interoperability-case-study.md para o limite exato.
O endurecimento atual de HID/APDU/OTP está registrado no Draft PR #7. Ele inclui um caminho de integração do SDK baseado em patches, testes de regressão no host e evidências de build ARM isolado local. Essas verificações não são um teste em dispositivo real, um teste completo de conformidade FIDO, uma certificação ou uma versão de produção. O GitHub Actions executa testes de host/código-fonte e verificações de publicação; builds ARM completos foram verificados localmente, não no GitHub Actions.
O branch main e seu build de referência não incluem automaticamente os patches não mesclados da v5.3. Para evidências experimentais atuais e bloqueios pendentes, use o PR #7 em vez de tratar hashes UF2 históricos ou aprovações individuais de testes como o status mais recente do hardware. Nenhum binário de firmware deste trabalho é oferecido para download ou gravação.
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 de chave de segurança; interfaces de runtime não relacionadas, do tipo teclado/CCID, não fazem parte do perfil de referência KL.
maingit 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 build main habilita a aplicação de presença física do usuário, o perfil de runtime somente FIDO e o caminho de atestação empacotada; ela não é uma build das alterações v5.3 não mescladas. Material válido de chave/certificado de atestação deve ser provisionado separadamente; chaves de atestação privadas não são publicadas nem provisionadas automaticamente por este repositório. Compilar um UF2 não autoriza gravar um dispositivo.
Este repositório não afirma: