Chaves SSH: Guia Completo para Gerar, Utilizar e Configurar como um Profissional

Já lhe aconteceu? Está a tentar aceder a um servidor, digita a password, e recebe a mensagem "Permission denied (publickey,password)". Tenta outra vez. Outra. E outra. Até que desiste e recorre ao suporte técnico, que lhe diz, com um ar de quem já viu isto mil vezes: "Tem de configurar a chave SSH."

A sensação de impotência é real. A autenticação por chave SSH é uma das tecnologias mais poderosas e mal compreendidas do mundo do desenvolvimento. A boa notícia? É mais simples do que parece.

Neste guia, vou mostrar-lhe exatamente como gerar, configurar e utilizar chaves SSH. Com passos detalhados que qualquer pessoa pode seguir, incluindo exemplos práticos para Windows, Linux, macOS e GitHub. No final, vai conseguir autenticar-se num servidor ou no GitHub sem nunca mais precisar de uma password.

Se trabalha com servidores ou faz deployment de aplicações, este guia complementa o nosso artigo sobre Node.js ou PHP: o que escolher para o seu projeto, onde abordamos a escolha da tecnologia backend que também impacta a forma como gere acessos e autenticação.

O que são Chaves SSH (e porque são melhores que passwords)

O SSH (Secure Shell) é o protocolo que usamos para aceder remotamente a servidores. A autenticação por chave pública é a forma mais segura de o fazer, especialmente quando combinada com boas práticas de segurança web.

O princípio é simples: gera um par de chaves (pública e privada). Coloca a chave pública no servidor. Mantém a chave privada no seu computador. Quando tenta aceder, o servidor usa a chave pública para verificar se a chave privada é legítima.

Porque as chaves SSH são melhores que passwords:

• A força de uma chave SSH é muito superior ao que um humano consegue memorizar
• Cada chave é única, ao contrário das passwords que as pessoas reutilizam
• As chaves SSH são imunes a ataques de força bruta
• A chave privada nunca é transmitida pela rede, ao contrário das passwords
• Uma vez configurada, a autenticação é transparente

Tipos de Chaves SSH: Qual escolher

A escolha do tipo de chave é o primeiro passo. Esta decisão é semelhante à escolha entre Node.js ou PHP para o backend - depende do contexto e dos requisitos do projeto. Aqui estão as opções atuais, com base na documentação oficial da OpenSSH.

Ed25519 (Recomendado)

Ed25519 é a escolha recomendada pela OpenSSH para novas configurações. Oferece aproximadamente 128 bits de segurança, chaves curtas, geração rápida e é suportado por todas as ferramentas modernas. É a opção padrão para a maioria dos casos de uso.

RSA 4096 bits

RSA continua a ser seguro quando configurado corretamente com 4096 bits, mas Ed25519 é normalmente preferível para novas configurações. RSA pode ser útil quando existe necessidade de compatibilidade com sistemas mais antigos que não suportam Ed25519.

ECDSA - geralmente não é a primeira escolha

ECDSA não é recomendado para novas chaves. Ed25519 é normalmente preferível pela simplicidade e pelas propriedades do esquema. Apenas para ambientes muito específicos onde Ed25519 não está disponível.

DSA (Descontinuado)

DSA utiliza parâmetros que já não são considerados adequados para uso moderno. A OpenSSH desativou DSA por defeito em versões recentes. Não use DSA.

FIDO2 Security Keys (ed25519-sk)

Se tiver uma chave de segurança FIDO2, pode usar ed25519-sk para autenticação com presença física. A chave privada é protegida pelo dispositivo e a autenticação exige interação física (toque no dispositivo). Consulte a FIDO Alliance para mais detalhes.

Resumo: Use Ed25519 em novos projetos. Use RSA 4096 apenas para compatibilidade com sistemas antigos. Evite ECDSA e não use DSA.

Acesso ao OpenSSH e Ferramentas

OpenSSH (Windows, macOS, Linux)

Windows 10/11: O OpenSSH Client vem instalado por padrão nas versões mais recentes. Para verificar se está disponível, abra o PowerShell e execute:

ssh -V

Se o comando não for reconhecido, pode instalar o cliente OpenSSH nas definições do Windows em "Aplicações" > "Aplicações e funcionalidades" > "Funcionalidades opcionais" > "Adicionar uma funcionalidade" > "Cliente OpenSSH". Consulte a documentação oficial da Microsoft para mais detalhes.

macOS e Linux: O OpenSSH vem pré-instalado na maioria das distribuições. Use o terminal para todos os comandos.

PuTTY

O PuTTY é uma ferramenta popular em Windows que inclui o PuTTYgen para gerar chaves SSH. Pode descarregar o PuTTY em https://www.putty.org/.

MobaXterm

O MobaXterm é uma ferramenta que inclui o MobaKeyGen para gerar chaves SSH. Pode descarregar em https://mobaxterm.mobatek.net/.

Tera Term

O Tera Term é uma alternativa que inclui um gerador de chaves SSH. Pode descarregar em https://teratermproject.github.io/.

Passo 1: Verificar se já tem chaves SSH

Antes de gerar novas chaves, verifique se já existem. É comum ter gerado uma sem se lembrar.

No terminal (Linux/macOS/Windows PowerShell):

# Verificar se existem chaves SSH
ls -la ~/.ssh/

Se vir ficheiros como id_ed25519 e id_ed25519.pub, ou id_rsa e id_rsa.pub, já tem chaves. Se não vir nada, ou apenas ficheiros de configuração, está na hora de gerar.

Passo 2: Gerar um par de chaves SSH

No OpenSSH (Terminal, PowerShell, Linux/macOS)

O comando ssh-keygen é a ferramenta padrão para gerar chaves SSH.

Para gerar uma chave Ed25519 (recomendado):

ssh-keygen -t ed25519 -C "seu-email@exemplo.com"

Para gerar uma chave RSA 4096 bits (para compatibilidade):

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

O que cada parte do comando significa:

• ssh-keygen - o comando para gerar chaves
• -t ed25519 - o tipo de chave (Ed25519 ou rsa)
• -b 4096 - o número de bits (apenas para RSA)
• -C - um comentário (normalmente o email, para identificar a chave)

Posso gerar uma chave sem email?

Sim, absolutamente. O parâmetro -C (comentário) é opcional. Se não fornecer um email, a chave será gerada na mesma. O comentário serve apenas para identificar a chave, especialmente quando tem várias chaves no servidor.

Se não quiser usar email:

ssh-keygen -t ed25519

O sistema vai gerar a chave sem comentário ou com um comentário padrão (normalmente o nome do utilizador e o nome do computador).

Se quiser um comentário personalizado sem ser email:

ssh-keygen -t ed25519 -C "chave-servidor-producao-2026"
ssh-keygen -t ed25519 -C "notebook-pessoal"
ssh-keygen -t ed25519 -C "github-deploy-key"

Dica: Sempre que possível, use um comentário descritivo. Quando tiver várias chaves no servidor (ex: uma para o seu portátil, outra para o servidor de CI/CD), o comentário ajuda a saber qual é qual.

Exemplo de chave pública com comentário:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... notebook-pessoal

Exemplo de chave pública sem comentário:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...

A chave funciona exatamente da mesma forma. A diferença é apenas a identificação visual.

O que acontece a seguir?

O sistema pergunta onde guardar a chave:

Enter file in which to save the key (/home/user/.ssh/id_ed25519):

Aperte Enter para aceitar a localização padrão. Depois pede uma passphrase:

Enter passphrase (empty for no passphrase):

A passphrase é recomendada. Se alguém roubar a sua chave privada, sem a passphrase não consegue usá-la. A passphrase deve ser de 10 a 100 caracteres, com maiúsculas, minúsculas, números e símbolos.

Exemplo completo no PowerShell

PS C:> ssh-keygen -t ed25519 -C "notebook-trabalho"
Generating public/private ed25519 key pair.
Enter file in which to save the key (C:Usersusername/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:Usersusername/.ssh/id_ed25519.
Your public key has been saved in C:Usersusername/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:sPWZyx1CASEFDuqR1dX7WkvKArMBnQnLFFwxZznv6Pw notebook-trabalho

Com o PuTTYgen (PuTTY)

1. Abra o PuTTYgen (normalmente no menu do PuTTY ou como executável separado)
2. Selecione o tipo de chave: Ed25519 (recomendado) ou RSA
3. Defina o número de bits para 4096 (se escolher RSA)
4. Clique em Generate e mova o rato sobre a área em branco para gerar entropia
5. Defina uma passphrase nos campos "Key passphrase" e "Confirm passphrase"
6. No campo "Key comment", pode escrever um identificador (ex: "servidor-producao", "meu-portatil", ou mesmo o seu email). Este campo é opcional.
7. Clique em Save private key para guardar a chave privada (formato .ppk)
8. A chave pública aparece no campo "Public key for pasting into OpenSSH authorized_keys file"

Com o MobaKeyGen (MobaXterm)

1. Abra o MobaXterm e vá ao menu Tools > MobaKeyGen (SSH key generator)
2. Escolha o tipo de chave (recomendado: EdDSA Ed25519)
3. Clique em Generate e mova o rato para gerar entropia
4. Defina uma passphrase para a chave privada
5. No campo "Comment", pode escrever um identificador (opcional)
6. Clique em Save private key para guardar a chave privada (formato .ppk)
7. A chave pública no formato OpenSSH aparece no campo "OpenSSH type public key"

Com o Tera Term

1. Abra o Tera Term e cancele a ligação inicial
2. Vá ao menu Setup > SSH KeyGenerator
3. Escolha o tipo de chave (recomendado: ED25519)
4. Defina a passphrase
5. No campo "Comment", pode escrever um identificador (opcional)
6. Clique em Generate
7. Clique em Save public key e Save private key para guardar ambos os ficheiros

Passo 3: Os ficheiros gerados

Depois de gerar as chaves, tem dois ficheiros na pasta ~/.ssh/:

Chave privada (id_ed25519 ou id_rsa):

-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
... (conteúdo encriptado) ...
-----END OPENSSH PRIVATE KEY-----

Nunca partilhe este ficheiro. É a sua chave de casa. Guarde-o como se fosse a chave do seu cofre.

Chave pública (id_ed25519.pub ou id_rsa.pub):

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... notebook-trabalho

Este ficheiro pode ser partilhado. É a fechadura que vai colocar nos servidores. A chave pública no formato OpenSSH é uma única linha que começa com ssh-ed25519 ou ssh-rsa, seguida da chave em si, e opcionalmente um comentário.

Passo 4: Configurar a chave pública no servidor

Agora que tem o par de chaves, precisa de colocar a chave pública no servidor.

No OpenSSH (Unix/Linux/macOS) - ssh-copy-id (recomendado)

Se tiver acesso ao servidor com password, use:

ssh-copy-id -i ~/.ssh/id_ed25519.pub utilizador@servidor.com

O comando pergunta a password do servidor, copia a sua chave pública para ~/.ssh/authorized_keys, e configura as permissões automaticamente.

No Windows PowerShell (se ssh-copy-id não estiver disponível)

type $env:USERPROFILE.sshid_ed25519.pub | ssh utilizador@servidor.com "cat >> .ssh/authorized_keys"

Este comando usa o type do Windows para ler o ficheiro da chave pública e envia-o para o servidor, onde é adicionado ao ficheiro authorized_keys.

Manual (Linux/macOS/Windows)

cat ~/.ssh/id_ed25519.pub | ssh utilizador@servidor.com "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Ou copie o conteúdo da chave pública e cole-o no ficheiro ~/.ssh/authorized_keys do servidor.

Permissões importantes no servidor:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Consulte a documentação oficial da OpenSSH para mais detalhes sobre permissões e configuração.

Se está a configurar um servidor para um projeto, lembre-se que a gestão de acessos é tão importante quanto a escolha da tecnologia. Veja o nosso artigo sobre Node.js ou PHP: o que escolher para o backend para uma visão mais ampla sobre a arquitetura do seu projeto.

Passo 5: Configurar o SSH Agent

Se colocou uma passphrase na chave privada, o SSH Agent guarda-a em memória para não ter de a repetir.

O que é o ssh-agent? O ssh-agent é um programa que corre em segundo plano e guarda as suas chaves privadas em memória. Quando precisa de usar SSH, o agente fornece a chave automaticamente, sem que tenha de introduzir a passphrase de cada vez.

O que é o ssh-add? O ssh-add é o comando que adiciona chaves ao agente. É como "entregar" a chave ao agente para ele guardar.

No Linux/macOS

Iniciar o agente e adicionar a chave:

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

No Windows PowerShell

Pode iniciar o agente de forma automática:

# Definir o agente para iniciar automaticamente
Set-Service ssh-agent -StartupType Automatic

# Iniciar o agente
Start-Service ssh-agent

# Adicionar a chave privada
ssh-add $env:USERPROFILE.sshid_ed25519

# Verificar as chaves carregadas
ssh-add -l

Comandos úteis do ssh-add:

# Listar as chaves carregadas no agente
ssh-add -l

# Remover uma chave específica do agente
ssh-add -d ~/.ssh/id_ed25519

# Remover todas as chaves do agente
ssh-add -D

O sistema pede a passphrase uma vez. A partir daí, fica guardada até terminar a sessão ou até reiniciar o computador.

No PuTTY (Pageant)

O Pageant é o agente SSH para o PuTTY. Execute o Pageant, clique com o botão direito no ícone na bandeja do sistema, e selecione "Add Key". Selecione o ficheiro .ppk da chave privada e introduza a passphrase.

No MobaXterm

O MobaXterm tem um agente integrado. Quando configurar uma sessão SSH com uma chave privada, a passphrase é pedida automaticamente na ligação.

Passo 6: Configurar o ficheiro ~/.ssh/config

O ficheiro ~/.ssh/config permite configurar atalhos para diferentes servidores. É uma das ferramentas mais poderosas para quem usa SSH regularmente.

Exemplo de configuração para servidores:

# Servidor de produção
Host producao
    HostName 192.168.1.100
    User deploy
    Port 22
    IdentityFile ~/.ssh/id_ed25519_producao
    IdentitiesOnly yes

# Servidor de staging
Host staging
    HostName staging.meuservidor.com
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_rsa_staging

O que fica mais fácil:

Em vez de escrever:

ssh -i ~/.ssh/id_ed25519_producao deploy@192.168.1.100 -p 22

Escreve apenas:

ssh producao

Exemplo de configuração para múltiplas contas GitHub:

# Conta pessoal
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

# Conta de trabalho
Host github-trabalho
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_trabalho
    IdentitiesOnly yes

Com esta configuração, para usar a conta de trabalho, faz:

git clone git@github-trabalho:empresa/repositorio.git

Esta organização de ficheiros e configurações é semelhante à forma como estruturamos projetos de software. Se está a desenvolver uma aplicação, veja o nosso artigo sobre quando vale a pena desenvolver software à medida para entender como a infraestrutura e acessos se integram no desenvolvimento.

Passo 7: Utilizar SSH com GitHub

O GitHub é um dos casos de uso mais comuns para chaves SSH. Em vez de usar username/password para cada operação Git, pode usar uma chave SSH.

Gerar uma chave para o GitHub

ssh-keygen -t ed25519 -C "github" -f ~/.ssh/id_ed25519_github

Adicionar a chave pública ao GitHub

1. Copie a chave pública: cat ~/.ssh/id_ed25519_github.pub
2. No GitHub, vá a Settings > SSH and GPG keys > New SSH Key
3. Cole a chave e guarde

Consulte a documentação oficial do GitHub para mais detalhes.

Testar a ligação ao GitHub

ssh -T git@github.com

Se funcionar, verá:

Hi seu-usuario! You have successfully authenticated, but GitHub does not provide shell access.

Diferença entre URL HTTPS e SSH

Para clonar um repositório com SSH, use o URL no formato:

git@github.com:utilizador/repositorio.git

Em vez de HTTPS:

https://github.com/utilizador/repositorio.git

Passo 8: Testar a configuração

Depois de tudo configurado, teste:

# Testar ligação ao servidor
ssh utilizador@servidor.com

# Se configurou o ficheiro config
ssh producao

# Testar GitHub (para quem usa Git)
ssh -T git@github.com

Se algo falhar, use o modo verboso para diagnóstico:

ssh -v utilizador@servidor.com

O modo verboso mostra detalhes da negociação, incluindo quais chaves estão a ser oferecidas e se o servidor as aceita. Procure linhas como:

debug1: Offering public key: /home/user/.ssh/id_ed25519
debug1: Server accepts key: /home/user/.ssh/id_ed25519
debug1: Authentication succeeded (publickey).

Para ver a configuração efetiva que o SSH está a usar:

ssh -G servidor-producao

Este comando mostra a configuração completa que o SSH vai aplicar para aquele host, incluindo o ficheiro IdentityFile, portas e opções.

Erros Comuns e Soluções

Erro: "Permission denied (publickey)"

Causa: A chave pública não está no servidor ou as permissões estão erradas.

Solução:

# Verificar permissões no servidor
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

# Verificar o conteúdo da chave pública local
cat ~/.ssh/id_ed25519.pub

# Comparar com a chave no servidor
cat ~/.ssh/authorized_keys

Use o modo verboso para diagnosticar:

ssh -v utilizador@servidor.com

Erro: "Connection refused" ou "Connection timed out"

Causa: O servidor não está a aceitar ligações ou o firewall está a bloquear a porta.

Solução: Verificar se o servidor está online e se a porta 22 está aberta.

Erro: "Agent admitted failure to sign"

Causa: O agente não tem a chave carregada.

Solução:

# Adicionar a chave ao agente
ssh-add ~/.ssh/id_ed25519

# Verificar as chaves carregadas
ssh-add -l

Erro: Muitas chaves carregadas

Se tiver muitas chaves no agente, o servidor pode rejeitar a ligação porque excedeu o número máximo de tentativas de autenticação.

Solução: Use a opção IdentitiesOnly no ~/.ssh/config para forçar o uso de uma chave específica:

Host servidor-producao
    IdentitiesOnly yes
    IdentityFile ~/.ssh/id_ed25519

Erro: "Bad permissions" no servidor

Causa: O ficheiro authorized_keys tem permissões demasiado permissivas.

Solução:

chmod 600 ~/.ssh/authorized_keys

Erro: "No such file or directory" no Windows

Causa: A pasta .ssh não existe.

Solução:

mkdir $env:USERPROFILE.ssh

Segurança Operacional

Backup da chave privada

A chave privada é o seu acesso a servidores. Se a perder, perde o acesso. No entanto, nunca guarde a chave privada numa cloud sem proteção (ex: Google Drive, Dropbox) sem encriptação.

Se precisar de fazer backup, use um cofre de passwords (ex: Bitwarden, 1Password) ou encripte o ficheiro com GPG antes de o guardar.

Esta prática de segurança alinha-se com as boas práticas que abordamos no artigo sobre segurança web: como proteger o seu site e os dados dos clientes, onde explicamos a importância de proteger acessos e dados sensíveis.

Revogação de chaves comprometidas

Se suspeitar que a sua chave privada foi comprometida:

1. Remova a chave pública do servidor: edite ~/.ssh/authorized_keys e elimine a linha correspondente
2. Remova a chave do GitHub/GitLab/etc.
3. Gere uma nova chave
4. Substitua a chave em todos os sistemas que dependem dela

Chaves por finalidade

Uma chave para o GitHub, outra para servidores pessoais, outra para clientes. Se uma chave for comprometida, o dano fica limitado a um serviço ou conjunto de servidores.

Esta abordagem de separação por responsabilidades é semelhante à que usamos no desenvolvimento de software, onde diferentes ambientes (desenvolvimento, staging, produção) têm diferentes níveis de acesso. Veja o nosso artigo sobre webdesign vs desenvolvimento web para entender como diferentes papéis e acessos se organizam num projeto.

Manter o OpenSSH atualizado

Mantenha o OpenSSH atualizado e consulte os avisos de segurança da sua distribuição e do projeto OpenSSH. Versões antigas podem conter vulnerabilidades já corrigidas em versões posteriores.

Ferramentas para Windows: Resumo

Nota sobre formatos: O PuTTY e MobaXterm usam o formato .ppk. O OpenSSH usa o formato padrão. MobaXterm aceita ambos. Para converter entre formatos, pode usar o PuTTYgen (menu "Conversions" > "Import key" e depois exportar no formato desejado).

Perguntas Frequentes

Posso gerar uma chave SSH sem email?

Sim, absolutamente. O parâmetro -C (comentário) é opcional. Pode gerar uma chave sem qualquer comentário ou com um comentário personalizado que não seja um email.

# Sem comentário
ssh-keygen -t ed25519

# Com comentário personalizado (não email)
ssh-keygen -t ed25519 -C "servidor-producao-2026"

Posso usar a mesma chave para vários serviços?

Sim, pode. Muitas pessoas usam a mesma chave SSH para o GitHub, servidores pessoais e outros serviços. No entanto, por questões de segurança, é recomendado usar chaves diferentes para serviços diferentes. Se uma chave for comprometida, o dano fica limitado.

Como listar as chaves carregadas no agente?

ssh-add -l

Como remover uma chave do agente?

# Remover uma chave específica
ssh-add -d ~/.ssh/id_ed25519

# Remover todas as chaves
ssh-add -D

Como forçar o uso de uma chave específica?

Use a opção -i:

ssh -i ~/.ssh/id_ed25519_producao utilizador@servidor.com

Ou configure no ~/.ssh/config:

Host servidor-producao
    IdentityFile ~/.ssh/id_ed25519_producao
    IdentitiesOnly yes

Se está a planear um projeto que envolva autenticação e gestão de acessos, estes conhecimentos são fundamentais. Para uma visão mais completa sobre como estruturar um projeto digital, veja o nosso guia sobre criação de sites profissionais em Portugal.