Clave SSH

Cuando haces push o pull a un repositorio remoto por SSH (por ejemplo, una URL con la forma [email protected]:...), Git necesita verificar tu identidad sin que tengas que escribir una contraseña cada vez. Las claves SSH resuelven este problema. Este capítulo explica qué es una clave SSH, cómo funciona el par de claves y cómo generarlas y registrarlas en un servidor remoto en macOS, Linux y Windows.

¿Qué son las claves SSH?

Una clave SSH es una credencial de acceso utilizada en el protocolo SSH (Secure Shell). SSH es un protocolo de red que te permite iniciar sesión de forma segura desde un equipo a otro, y administrar servidores, sistemas operativos y configuraciones a través de una conexión cifrada. Funcionalmente, las claves SSH cumplen el mismo papel que una contraseña, pero son mucho más seguras: la clave nunca se envía por la red y es computacionalmente inviable derivar la clave privada a partir de la clave pública.

Las claves SSH siempre vienen en pares, y cada par está compuesto por una clave pública y una clave privada:

1. Clave pública (también llamada clave autorizada). La compartes libremente y la añades a cada sistema al que quieres acceder. Determina quién tiene permitido entrar.
2. Clave privada (también llamada clave de identidad). Permanece en secreto en tu máquina y nunca debe compartirse. Prueba tu identidad ante cualquier servidor que tenga la clave pública correspondiente.

Ambas están matemáticamente vinculadas. Un servidor cifra un desafío con tu clave pública; solo el titular de la clave privada correspondiente puede responderlo. Así es como funciona la autenticación sin transmitir nunca un secreto.

Por qué usar claves SSH con Git

• Sin contraseña en cada push. Una vez que la clave está registrada, git push, git pull y git fetch por SSH se autentican de forma silenciosa.
• Más seguras que las contraseñas. Las claves no pueden adivinarse ni forzarse por fuerza bruta como sí ocurre con contraseñas cortas.
• Requeridas por muchos servicios. GitHub ya no acepta contraseñas de cuenta para operaciones Git; las claves SSH (o tokens) son el estándar.

Para clonar un repositorio con SSH una vez configurada tu clave, usa la forma git@ de la URL. Consulta Git Clone y Git Remote para saber cómo se especifican los remotos.

¿Cómo configurar claves SSH?

Las claves SSH se generan con una herramienta de generación de claves, casi siempre ssh-keygen, que viene incluida con el cliente OpenSSH. Utiliza algoritmos criptográficos de clave pública; los más comunes son Ed25519 (moderno, corto, rápido, recomendado) y RSA. Algoritmos más antiguos como DSA existen pero ahora se consideran débiles y están deshabilitados por defecto en las versiones actuales de OpenSSH.

El flag -t selecciona el algoritmo. Dos opciones comunes:

# Recommended: Ed25519
ssh-keygen -t ed25519 -C "[email protected]"

# Compatibility fallback: RSA with a 4096-bit key
ssh-keygen -t rsa -b 4096 -C "[email protected]"

El flag -C añade un comentario (normalmente tu correo electrónico) para que la clave sea fácil de identificar en una lista de claves autorizadas.

Crear una clave SSH en Mac y Linux

Ambos sistemas operativos incluyen un terminal moderno y el paquete OpenSSH, por lo que los pasos son idénticos.

1. Abre un terminal y ejecuta:

Generar el par de claves

ssh-keygen -t ed25519 -C "[email protected]"

2. Elige dónde guardar la clave. Presiona Enter para aceptar la ubicación predeterminada (~/.ssh/id_ed25519):

Elegir la ubicación del archivo

> Enter a file in which to save the key (~/.ssh/id_ed25519): [Press enter]

Esto crea dos archivos: la clave privada id_ed25519 y la clave pública id_ed25519.pub.

3. Establece una frase de contraseña. Esto cifra la clave privada en el disco, de modo que incluso un archivo de clave robado sea inútil sin ella. Se te pedirá cuando la clave se use por primera vez en una sesión:

Establecer una frase de contraseña

> Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

4. Añade la nueva clave SSH al ssh-agent. El ssh-agent mantiene tus claves privadas descifradas en memoria y firma las solicitudes de autenticación en tu nombre, de modo que solo tienes que escribir la frase de contraseña una vez por sesión.

Ejecuta el siguiente comando para asegurarte de que el ssh-agent está en ejecución:

Clave SSH en Linux

eval "$(ssh-agent -s)"
> Agent pid 59566

Si el ssh-agent está en ejecución, añade la nueva clave SSH al agente SSH local ejecutando el siguiente comando:

Clave SSH

ssh-add ~/.ssh/id_ed25519

(Nota: En versiones modernas de macOS (OpenSSH 8.8+), ssh-add -K está obsoleto. En su lugar, añade AddKeysToAgent yes a tu archivo ~/.ssh/config para que las claves se persistan automáticamente en el llavero.)

5. Copia la clave pública al servidor remoto. Para usar la clave en la autenticación, debes añadirla al archivo ~/.ssh/authorized_keys del servidor remoto. Ejecuta el siguiente comando desde tu máquina local:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote_host

6. Verifica la conexión. Comprueba que puedes iniciar sesión en el servidor remoto usando tu nueva clave:

ssh user@remote_host

Crear una clave SSH en Windows

Necesitas Git Bash para crear una clave SSH en el sistema operativo Windows. Abre Git Bash y ejecuta el siguiente comando para generar la clave:

ssh-keygen -t ed25519 -C "[email protected]"

Sigue las mismas indicaciones que se describieron arriba para establecer la ubicación del archivo y la frase de contraseña. Después de generar la clave, cópiala a tu servidor remoto o servicio de alojamiento Git usando el comando ssh-copy-id, o pegando el contenido de id_ed25519.pub en la configuración de claves SSH del servicio.

Añadir tu clave a GitHub, GitLab o Bitbucket

Un servicio de alojamiento Git no es un servidor SSH que controles, por lo que ssh-copy-id no se aplica — en su lugar pegas la clave pública en la interfaz web. Imprime la clave pública y cópiala:

cat ~/.ssh/id_ed25519.pub

La salida es una sola línea que comienza con ssh-ed25519 y termina con el comentario que estableciste:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... [email protected]

Copia toda esa línea y agrégala en la configuración de claves SSH de tu cuenta (en GitHub: Settings → SSH and GPG keys → New SSH key). Luego verifica la conexión:

ssh -T [email protected]

Una primera conexión exitosa te pedirá que confirmes la huella digital del host y luego te saludará por nombre de usuario — no abre un shell, lo cual es lo esperado para GitHub.

Una vez registrada la clave, cambia tu remoto a la URL SSH para que los pushes la utilicen:

git remote set-url origin [email protected]:user/repo.git

Consulta Git Remote para gestionar URLs de remotos y Git Push para enviar tus commits.

Problemas comunes y consejos

• Permission denied (publickey) generalmente significa que el host no tiene una clave pública coincidente, o que el agente no tiene tu clave privada. Ejecuta ssh-add -l para listar las claves cargadas y vuelve a añadir la tuya si es necesario.
• Reutiliza una clave en varios hosts. Un solo par de claves puede autenticarse en muchos servidores; no necesitas una clave nueva por proyecto. Genera una clave separada solo cuando quieras aislar el acceso.
• Haz una copia de seguridad de tus claves, no solo de tus repositorios. Perder ~/.ssh/id_ed25519 significa regenerar y volver a registrar en todas partes.
• Las claves SSH autentican conexiones; si también quieres demostrar quién es el autor de un commit, ese es un mecanismo separado — consulta Signing Commits. Para la configuración inicial, consulta Install Git y Git Config.

Práctica