Claves SSH: cómo funcionan y cómo crear una

SSH (Secure Shell) es el protocolo que usas para entrar en servidores y para hacer git push sin escribir usuario y contraseña cada vez. En lugar de una contraseña, puede autenticarte con un par de claves criptográficas.

Este modelo es más seguro que una contraseña por una razón sencilla: el secreto nunca viaja por la red.

¿Cómo funciona una clave SSH?#

Generas dos archivos vinculados matemáticamente:

• Clave privada (por ejemplo id_ed25519): se queda solo en tu máquina. Es el secreto.
• Clave pública (id_ed25519.pub): se puede copiar a cualquier lugar. Queda en el servidor o en tu cuenta de GitHub.

Al conectar, el servidor envía un desafío. Tu cliente SSH firma el desafío con la clave privada, y el servidor comprueba la firma con la pública. Si coincide, entras. La clave privada en sí nunca se envía.

Quien tiene solo la clave pública no puede hacerse pasar por ti. Quien tiene la privada sí, así que trátala con el mismo cuidado que la contraseña del banco.

¿Cómo se genera una clave SSH?#

El comando es el mismo en Linux, macOS y Windows (PowerShell o Git Bash):

ssh-keygen -t ed25519 -C "tu@ejemplo.com"

• -t ed25519 elige el tipo.
• -C añade un comentario (usa el correo de tu cuenta de GitHub).

El programa pregunta dónde guardarla: presiona Enter para aceptar la ruta por defecto (~/.ssh/id_ed25519). Después pide una passphrase. Define una. La passphrase cifra el archivo de la clave privada: si alguien copia el archivo, aún necesita la frase.

Al final hay dos archivos en ~/.ssh/: id_ed25519 (privada) e id_ed25519.pub (pública).

¿Qué tipo de clave conviene usar?#

En la mayoría de los casos, Ed25519. Es el tipo que la documentación de GitHub usa por defecto en sus ejemplos.

Si el sistema o un servidor antiguo no acepta Ed25519, usa RSA de 4096 bits:

ssh-keygen -t rsa -b 4096 -C "tu@ejemplo.com"

¿Cómo usar ssh-agent para no escribir la passphrase a cada rato?#

ssh-agent guarda la clave desbloqueada en memoria durante la sesión.

En Linux y macOS:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

En macOS, para guardar la passphrase en el Llavero, usa ssh-add --apple-use-keychain ~/.ssh/id_ed25519 y crea el archivo ~/.ssh/config con:

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

En Windows, abre PowerShell como administrador y activa el servicio:

Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent

Después, en una terminal sin privilegios de administrador:

ssh-add c:/Users/TU_USUARIO/.ssh/id_ed25519

¿Cómo se registra la clave pública en GitHub?#

1. Copia el contenido del archivo .pub, sin espacios ni saltos de línea de más:
   • macOS: pbcopy < ~/.ssh/id_ed25519.pub
   • Windows (PowerShell): cat ~/.ssh/id_ed25519.pub | clip
   • Linux: cat ~/.ssh/id_ed25519.pub y copia la salida.
2. En GitHub, haz clic en tu foto de perfil y luego en Settings.
3. En la barra lateral, en Access, abre SSH and GPG keys.
4. Haz clic en New SSH key, ponle un título (por ejemplo "laptop personal"), elige el tipo Authentication y pega la clave.
5. Haz clic en Add SSH key. GitHub puede pedirte que confirmes tu identidad.

En servidores propios, el paso equivalente es añadir la línea de la clave pública al archivo ~/.ssh/authorized_keys del usuario en el servidor.

¿Cómo compruebas que funcionó?#

ssh -T git@github.com

En la primera conexión, SSH muestra una huella (fingerprint) y pregunta Are you sure you want to continue connecting (yes/no)?. Compara la huella con la página oficial de fingerprints de GitHub antes de escribir yes. Si todo está bien, la respuesta es:

Hi TU_USUARIO! You've successfully authenticated, but GitHub does not provide shell access.

El mensaje habla de "sin acceso a shell" porque GitHub solo acepta comandos de Git. El comando termina con código 1, y eso es lo esperado.

Para clonar por SSH, usa una URL con el formato git@github.com:usuario/repositorio.git.

¿Cuáles son los errores más comunes?#

Permission denied (publickey): el servidor no reconoció ninguna clave. Comprueba que la pública esté registrada en la cuenta correcta, que la privada se haya añadido al agente (ssh-add -l lista las claves cargadas) y que la URL del remoto use git@github.com:, no https://.

Windows no usa la clave cargada en el agente: Git puede estar usando otro binario de SSH, no el del sistema. Obliga a Git a usar el cliente de Windows, donde el agente guarda la clave:

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

Bad configuration option: usekeychain en macOS: añade IgnoreUnknown UseKeychain al mismo bloque Host del archivo ~/.ssh/config.

¿Cómo proteges tu clave privada?#

• Nunca subas la clave privada a un repositorio, chat o ticket. Si ocurre, trátala como filtrada: elimina la pública correspondiente de GitHub y genera otro par. La guía sobre una clave de API expuesta en GitHub sigue la misma lógica de revocación.
• Usa una passphrase y una clave por máquina. Así, perder una laptop invalida solo una clave.
• Dale un título claro a cada clave en GitHub y borra las que ya no uses.
• Para automatizaciones como el deploy con GitHub Actions, usa credenciales guardadas como secrets, nunca tu clave personal.
• Repasa la checklist de seguridad para publicar un bot, sitio o API.

Cómo hacerlo en Square Cloud#

En Square Cloud no necesitas una clave SSH para hacer deploy. Las formas de deploy son subir un ZIP en el panel, la CLI, GitHub (un push hace deploy, con la GitHub Action oficial o un webhook) y la extensión de VS Code. La CLI inicia sesión aprobando un código en el navegador o, en CI, lee la clave de la variable SQUARECLOUD_API_KEY.

No se permiten conexiones salientes por el puerto 22, así que la aplicación no puede abrir SSH hacia otro servidor ni clonar un repositorio por git@. Para acceder a un repositorio privado, usa HTTPS con un token. Guarda ese token, y cualquier otro secreto, en las variables de entorno de la aplicación (en el panel, la API, la CLI o VS Code), nunca en el código ni en el ZIP. El cambio se aplica en el siguiente reinicio, sin rebuild.

Mira cómo configurarlas en variables de entorno en Square Cloud.