Chaves SSH: como funcionam e como criar

SSH (Secure Shell) é o protocolo que você usa para acessar servidores e para fazer git push sem digitar usuário e senha a cada vez. Em vez de uma senha, ele pode autenticar você com um par de chaves criptográficas.

Esse modelo é mais seguro que senha por um motivo simples: o segredo nunca viaja pela rede.

Como funciona uma chave SSH?#

Você gera dois arquivos ligados matematicamente:

• Chave privada (por exemplo id_ed25519): fica só na sua máquina. É o segredo.
• Chave pública (id_ed25519.pub): pode ser copiada para qualquer lugar. Fica no servidor ou na sua conta do GitHub.

Na conexão, o servidor envia um desafio. Seu cliente SSH assina o desafio com a chave privada, e o servidor confere a assinatura com a pública. Se bater, você entra. A chave privada em si nunca é enviada.

Quem tem só a chave pública não consegue se passar por você. Quem tem a privada consegue, então trate-a com o mesmo cuidado que a senha do seu banco.

Como gerar uma chave SSH?#

O comando é o mesmo no Linux, macOS e Windows (PowerShell ou Git Bash):

ssh-keygen -t ed25519 -C "voce@exemplo.com"

• -t ed25519 escolhe o tipo.
• -C adiciona um comentário (use o e-mail da sua conta GitHub).

O programa pergunta onde salvar: aperte Enter para aceitar o padrão (~/.ssh/id_ed25519). Depois ele pede uma passphrase. Defina uma. Ela criptografa o arquivo da chave privada: se alguém copiar o arquivo, ainda precisa da frase.

Ao final existem dois arquivos em ~/.ssh/: id_ed25519 (privada) e id_ed25519.pub (pública).

Qual tipo de chave usar?#

Para a maioria dos casos, Ed25519. É o tipo que a documentação do GitHub usa como padrão nos exemplos.

Se o sistema ou o servidor antigo não aceitar Ed25519, use RSA com 4096 bits:

ssh-keygen -t rsa -b 4096 -C "voce@exemplo.com"

Como usar o ssh-agent para não digitar a passphrase toda hora?#

O ssh-agent guarda a chave desbloqueada na memória durante a sessão.

No Linux e no macOS:

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

No macOS, para guardar a passphrase no Keychain, use ssh-add --apple-use-keychain ~/.ssh/id_ed25519 e crie o arquivo ~/.ssh/config com:

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

No Windows, abra o PowerShell como administrador e ative o serviço:

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

Depois, em um terminal sem privilégio de administrador:

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

Como cadastrar a chave pública no GitHub?#

1. Copie o conteúdo do arquivo .pub, sem espaços ou quebras de linha extras:
   • macOS: pbcopy < ~/.ssh/id_ed25519.pub
   • Windows (PowerShell): cat ~/.ssh/id_ed25519.pub | clip
   • Linux: cat ~/.ssh/id_ed25519.pub e copie a saída.
2. No GitHub, clique na sua foto, depois em Settings.
3. Na barra lateral, em Access, abra SSH and GPG keys.
4. Clique em New SSH key, dê um título (por exemplo "notebook pessoal"), escolha o tipo Authentication e cole a chave.
5. Clique em Add SSH key. O GitHub pode pedir para confirmar sua identidade.

Em servidores próprios, o processo equivalente é acrescentar a linha da chave pública ao arquivo ~/.ssh/authorized_keys do usuário no servidor.

Como testar se funcionou?#

ssh -T git@github.com

Na primeira conexão, o SSH mostra uma impressão digital (fingerprint) e pergunta Are you sure you want to continue connecting (yes/no)?. Compare a impressão digital com a página oficial de fingerprints do GitHub antes de digitar yes. Se tudo estiver certo, a resposta é:

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

A mensagem fala em "sem acesso a shell" porque o GitHub só aceita comandos do Git. O comando sai com código 1, e isso é esperado.

Para clonar por SSH, use a URL no formato git@github.com:usuario/repositorio.git.

Quais são os erros mais comuns?#

Permission denied (publickey): o servidor não reconheceu nenhuma chave. Confira se a pública está cadastrada na conta certa, se a privada foi adicionada ao agente (ssh-add -l lista as chaves carregadas) e se a URL do remoto usa git@github.com:, não https://.

Windows não usa a chave carregada no agente: o Git pode estar usando outro binário SSH, e não o do sistema. Force o Git a usar o cliente do Windows, onde o agente guarda a chave:

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

Bad configuration option: usekeychain no macOS: adicione IgnoreUnknown UseKeychain ao mesmo bloco Host do arquivo ~/.ssh/config.

Como proteger sua chave privada?#

• Nunca envie a chave privada para um repositório, chat ou ticket. Se isso acontecer, trate como vazada: remova a pública correspondente do GitHub e gere outro par. O guia sobre chave de API exposta no GitHub segue a mesma lógica de revogação.
• Use uma passphrase e uma chave por máquina. Assim, perder um notebook invalida só uma chave.
• Dê um título claro a cada chave no GitHub e apague as que você não usa mais.
• Para automações como o deploy com GitHub Actions, prefira credenciais guardadas como secrets, nunca a sua chave pessoal.
• Revise o checklist de segurança para quem publica bot, site ou API.

Como fazer isso na Square Cloud#

Na Square Cloud você não precisa de chave SSH para publicar. As formas de deploy são upload de ZIP no painel, CLI, GitHub (push faz deploy, via GitHub Action oficial ou webhook) e extensão do VS Code. A CLI faz login aprovando um código no navegador ou, em CI, lê a chave da variável SQUARECLOUD_API_KEY.

Conexões de saída na porta 22 não são permitidas, então a aplicação não abre SSH para outro servidor nem clona repositório por git@. Para acessar um repositório privado, use HTTPS com um token. Guarde esse token, e qualquer outro segredo, nas variáveis de ambiente da aplicação (no painel, na API, na CLI ou no VS Code), nunca no código nem no ZIP. A mudança vale no próximo restart, sem rebuild.

Veja como configurar em variáveis de ambiente na Square Cloud.