YubiKey para SSH e GitHub: o guia técnica para developers
A tua chave SSH privada vive num ficheiro de texto plano em ~/.ssh/. Se alguém aceder ao teu portátil ou o infectar com malware, pode copiá-la em segundos. Não precisa da tua palavra-passe nem da tua impressão digital.
Uma YubiKey muda isso. A chave privada nunca sai do hardware — nem tu consegues exportá-la. Sem a chave física na porta USB ou perto da NFC, não há autenticação possível.
- Uma chave SSH suportada por hardware FIDO2
- Assinatura de commits de Git com essa mesma chave
- YubiKey como chave de segurança no GitHub (2FA)
Por que muda o modelo de ameaça
Uma chave SSH normal é um ficheiro. Pode ser copiada, filtrada numa cópia de segurança mal configurada ou roubada por malware que lê o disco.
Uma chave SSH suportada por YubiKey (-sk, de "security key") gera-se dentro do chip FIDO2. O sistema guarda apenas uma referência. Sem a chave física conectada, essa referência não serve para nada.
Além disso, podes exigir verificação táctil em cada utilização. Ainda que alguém tenha acesso remoto à tua máquina, precisaria tocar fisicamente na YubiKey para autenticar.
Gerar uma chave SSH suportada por YubiKey
Precisas de OpenSSH 8.2 ou superior. Vem incluído no macOS e na maioria das distribuições Linux modernas. No Windows, usa o cliente OpenSSH integrado ou WSL.
Executa ssh-keygen -t ed25519-sk -O resident -O verify-required -C "teu-email@dominio.com". A opção resident guarda a chave também na YubiKey, não apenas no teu disco.
O terminal pedir-te-á o PIN da YubiKey e depois tocar no sensor. Assim gera-se o par de chaves dentro do chip.
Gera-se id_ed25519_sk.pub em ~/.ssh/. Essa é a que adicionas ao GitHub, GitLab ou ao authorized_keys do teu servidor.
Conecta por SSH como sempre. O sistema pedir-te-á tocar na YubiKey antes de autenticar.
Com -O resident podes recuperar a chave da própria YubiKey num equipamento novo, com ssh-keygen -K. Não precisas de a gerar de raiz outra vez.
Assinar os teus commits de Git com a mesma chave
Desde Git 2.34 podes assinar commits usando uma chave SSH em vez de GPG. É a mesma YubiKey, sem configurar um segundo sistema de assinatura.
Executa git config --global gpg.format ssh.
Executa git config --global user.signingkey ~/.ssh/id_ed25519_sk.pub.
Executa git config --global commit.gpgsign true. Cada commit pedirá tocar na YubiKey.
Em Settings → SSH and GPG keys → New SSH key, carrega a mesma chave pública mas como tipo Signing Key, não Authentication Key.
A partir daqui, os teus commits aparecem como Verified no GitHub. Qualquer um pode comprovar que saíram da tua chave física, não apenas do teu nome de utilizador.
Ativar a YubiKey como 2FA no GitHub
Settings → Password and authentication → Security keys → Add.
Por USB ou por NFC, consoante o modelo. GitHub detecta-a como chave WebAuthn/FIDO2.
Confirma o registo. A partir de agora, o login pedirá a chave física, não um código temporário.
GitHub permite adicionar várias chaves como método de 2FA. Regista uma principal e uma de backup desde o primeiro dia.
Modelos YubiKey compatíveis para este fluxo
| Modelo | Conector | SSH (FIDO2) | 2FA GitHub |
|---|---|---|---|
| YubiKey 5 NFC | USB-A + NFC | ✓ | ✓ |
| YubiKey 5C NFC | USB-C + NFC | ✓ | ✓ |
| Security Key NFC | USB-A + NFC | ✓ | ✓ |
| Security Key C NFC | USB-C + NFC | ✓ | ✓ |
Os quatro modelos usam o protocolo FIDO2 para gerar chaves -sk, portanto o fluxo de SSH e de 2FA no GitHub funciona igual em todos. A diferença está na porta física do teu equipamento.
Como organizar a tua chave principal e a tua cópia de segurança
Se perderes a tua única YubiKey, perdes acesso a SSH, aos teus commits assinados e ao login do GitHub. Regista sempre uma segunda chave e guarda-a num sítio diferente da principal.
Suporte Carteira 2 Ranhuras
Leva a tua chave principal e a tua cópia de segurança juntas, em formato cartão de crédito. Fabricado em Espanha (UE).
Chaveiro com Lanyard
Para a chave que usas diariamente. NFC funciona sem tirar da capa. Fabricado em Espanha (UE).
Perguntas frequentes
Preciso de duas YubiKeys sim ou sim?
Não é obrigatório, mas é recomendável. Sem uma chave de segurança registada, uma falha ou uma perda deixa-te sem acesso a SSH e à tua conta do GitHub até usares outro método de recuperação.
Funciona igual no Windows, macOS e Linux?
Sim, desde que tenhas OpenSSH 8.2 ou superior. macOS e as distribuições Linux recentes incluem-no por predefinição. No Windows, usa o cliente OpenSSH do sistema ou WSL.
Posso usar a mesma YubiKey para SSH e para o meu Gmail?
Sim. Uma mesma YubiKey suporta múltiplas credenciais FIDO2, uma para cada serviço onde a registares — SSH, GitHub, Gmail e demais contas compatíveis com WebAuthn.
O que acontece se perder a YubiKey que usei para assinar commits?
Os commits já assinados continuam válidos. Para continuares a assinar, regista a chave de segurança como nova Signing Key no GitHub e atualiza user.signingkey na tua configuração de Git.
Vale a pena migrar SSH e GitHub para YubiKey?
Se trabalhas com acesso SSH a servidores de produção ou manténs repositórios com colaboradores, sim. A chave privada deixa de ser um ficheiro copiável e passa a depender de hardware físico.
O custo real não é o da chave, mas o de não teres uma de segurança organizada. Resolve isso desde o primeiro dia.
Como Associado da Amazon, recebo comissões por compras elegíveis.
