YubiKey para SSH y GitHub: la guía técnica para developers
Tu clave SSH privada vive en un archivo de texto plano en ~/.ssh/. Si alguien accede a tu portátil o lo infecta con malware, puede copiarla en segundos. No necesita tu contraseña ni tu huella.
Una YubiKey cambia eso. La clave privada nunca sale del hardware — ni siquiera tú puedes exportarla. Sin la llave física en el puerto USB o cerca del NFC, no hay autenticación posible.
- Una clave SSH respaldada por hardware FIDO2
- Firma de commits de Git con esa misma llave
- YubiKey como llave de seguridad en GitHub (2FA)
Por qué cambia el modelo de amenaza
Una clave SSH normal es un archivo. Se puede copiar, filtrar en un backup mal configurado o robar con malware que lee el disco.
Una clave SSH respaldada por YubiKey (-sk, de "security key") se genera dentro del chip FIDO2. El sistema solo guarda una referencia. Sin la llave física conectada, esa referencia no sirve de nada.
Además, puedes exigir verificación táctil en cada uso. Aunque alguien tenga acceso remoto a tu máquina, necesitaría tocar físicamente la YubiKey para autenticar.
Generar una clave SSH respaldada por YubiKey
Necesitas OpenSSH 8.2 o superior. Viene incluido en macOS y en la mayoría de distribuciones Linux modernas. En Windows, usa el cliente OpenSSH integrado o WSL.
Ejecuta ssh-keygen -t ed25519-sk -O resident -O verify-required -C "tu-email@dominio.com". La opción resident guarda la clave también en la YubiKey, no solo en tu disco.
El terminal te pedirá el PIN de la YubiKey y luego tocar el sensor. Así se genera el par de claves dentro del chip.
Se genera id_ed25519_sk.pub en ~/.ssh/. Esa es la que añades a GitHub, GitLab o al authorized_keys de tu servidor.
Conecta por SSH como siempre. El sistema te pedirá tocar la YubiKey antes de autenticar.
Con -O resident puedes recuperar la clave desde la propia YubiKey en un equipo nuevo, con ssh-keygen -K. No necesitas volver a generarla desde cero.
Firmar tus commits de Git con la misma llave
Desde Git 2.34 puedes firmar commits usando una clave SSH en lugar de GPG. Es la misma YubiKey, sin configurar un segundo sistema de firma.
Ejecuta git config --global gpg.format ssh.
Ejecuta git config --global user.signingkey ~/.ssh/id_ed25519_sk.pub.
Ejecuta git config --global commit.gpgsign true. Cada commit pedirá tocar la YubiKey.
En Settings → SSH and GPG keys → New SSH key, sube la misma clave pública pero como tipo Signing Key, no Authentication Key.
A partir de aquí, tus commits aparecen como Verified en GitHub. Cualquiera puede comprobar que salieron de tu llave física, no solo de tu nombre de usuario.
Activar la YubiKey como 2FA en GitHub
Settings → Password and authentication → Security keys → Add.
Por USB o por NFC, según el modelo. GitHub la detecta como llave WebAuthn/FIDO2.
Confirma el registro. A partir de ahora, el login pedirá la llave física, no un código temporal.
GitHub permite añadir varias llaves como método de 2FA. Registra una principal y una de backup desde el primer día.
Modelos YubiKey compatibles para este flujo
| 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 | ✓ | ✓ |
Los cuatro modelos usan el protocolo FIDO2 para generar claves -sk, así que el flujo de SSH y de 2FA en GitHub funciona igual en todos. La diferencia está en el puerto físico de tu equipo.
Cómo organizar tu llave principal y tu backup
Si pierdes tu única YubiKey, pierdes acceso a SSH, a tus commits firmados y al login de GitHub. Registra siempre una segunda llave y guárdala en un sitio distinto a la principal.
Soporte Tarjetero 2 Ranuras
Lleva tu llave principal y tu backup juntas, en formato tarjeta de crédito. Fabricado en España (UE).
Llavero con Lanyard
Para la llave que usas a diario. NFC funciona sin sacarla de la funda. Fabricado en España (UE).
Preguntas frecuentes
¿Necesito dos YubiKeys sí o sí?
No es obligatorio, pero sí recomendable. Sin una llave de backup registrada, un fallo o una pérdida te deja sin acceso a SSH y a tu cuenta de GitHub hasta que uses otro método de recuperación.
¿Funciona igual en Windows, macOS y Linux?
Sí, siempre que tengas OpenSSH 8.2 o superior. macOS y las distribuciones Linux recientes lo incluyen por defecto. En Windows, usa el cliente OpenSSH del sistema o WSL.
¿Puedo usar la misma YubiKey para SSH y para mi Gmail?
Sí. Una misma YubiKey admite múltiples credenciales FIDO2, una por cada servicio donde la registres — SSH, GitHub, Gmail y demás cuentas compatibles con WebAuthn.
¿Qué pasa si pierdo la YubiKey que usé para firmar commits?
Los commits ya firmados siguen siendo válidos. Para seguir firmando, registra la llave de backup como nueva Signing Key en GitHub y actualiza user.signingkey en tu configuración de Git.
¿Merece la pena migrar SSH y GitHub a YubiKey?
Si trabajas con acceso SSH a servidores de producción o mantienes repositorios con colaboradores, sí. La clave privada deja de ser un archivo copiable y pasa a depender de hardware físico.
El coste real no es el de la llave, sino el de no tener una de backup organizada. Resuelve eso desde el primer día.
Como Afiliado de Amazon, obtengo ingresos por las compras adscritas que cumplen los requisitos aplicables.
