Chave SSH

Quando você faz push ou pull em um repositório remoto via SSH (por exemplo, uma URL [email protected]:...), o Git precisa comprovar sua identidade sem digitar uma senha a cada vez. As chaves SSH resolvem esse problema. Este capítulo explica o que é uma chave SSH, como o par de chaves funciona e como gerar uma e registrá-la em um servidor remoto no macOS, Linux e Windows.

O que são Chaves SSH?

Uma chave SSH é uma credencial de acesso usada no protocolo SSH (Secure Shell). O SSH é um protocolo de rede que permite fazer login de um computador em outro com segurança, além de gerenciar servidores, sistemas operacionais e configurações por meio de uma conexão criptografada. Funcionalmente, as chaves SSH desempenham o mesmo papel que uma senha, mas são muito mais seguras: a chave nunca é enviada pela rede, e derivar a chave privada a partir da chave pública é computacionalmente inviável.

As chaves SSH sempre vêm em pares, e cada par é composto por uma chave pública e uma chave privada:

1. Chave pública (também chamada de authorized key). Você a compartilha livremente e a adiciona a cada sistema que deseja acessar. Ela determina quem tem permissão de entrada.
2. Chave privada (também chamada de identity key). Esta permanece em segredo na sua máquina e nunca deve ser compartilhada. Ela comprova sua identidade para qualquer servidor que possua a chave pública correspondente.

As duas estão matematicamente vinculadas. Um servidor criptografa um desafio com sua chave pública; somente o detentor da chave privada correspondente pode respondê-lo. É assim que a autenticação ocorre sem nunca transmitir um segredo.

Por que usar chaves SSH com o Git

• Sem senha a cada push. Uma vez que a chave está registrada, git push, git pull e git fetch via SSH autenticam silenciosamente.
• Mais seguras que senhas. As chaves não podem ser adivinhadas ou descobertas por força bruta como senhas curtas.
• Exigidas por muitos hosts. O GitHub não aceita mais senhas de conta para operações Git; chaves SSH (ou tokens) são o padrão.

Para clonar um repositório com SSH após configurar sua chave, use a forma git@ da URL. Consulte Git Clone e Git Remote para saber como os remotos são endereçados.

Como Configurar Chaves SSH?

Você gera chaves SSH com uma ferramenta de geração de chaves, quase sempre o ssh-keygen, que vem junto com o cliente OpenSSH. Ele usa algoritmos criptográficos de chave pública; os mais comuns são Ed25519 (moderno, curto, rápido, recomendado) e RSA. Algoritmos mais antigos como o DSA existem, mas hoje são considerados fracos e estão desabilitados por padrão no OpenSSH atual.

O sinalizador -t seleciona o algoritmo. Duas opções comuns:

# 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]"

O sinalizador -C adiciona um comentário (normalmente seu e-mail) para que a chave seja facilmente identificada em uma lista de chaves autorizadas.

Criar uma Chave SSH no Mac e Linux

Ambos os sistemas operacionais vêm com um terminal moderno e o pacote OpenSSH, portanto os passos são idênticos.

1. Abra um terminal e execute:

Gerar o par de chaves

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

2. Escolha onde salvar a chave. Pressione Enter para aceitar o local padrão (~/.ssh/id_ed25519):

Escolher o local do arquivo

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

Isso cria dois arquivos: a chave privada id_ed25519 e a chave pública id_ed25519.pub.

3. Defina uma frase-senha. Isso criptografa a chave privada no disco, de modo que mesmo um arquivo de chave roubado seja inútil sem ela. Você será solicitado a fornecê-la sempre que a chave for usada pela primeira vez em uma sessão:

Definir uma frase-senha

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

4. Adicione a nova chave SSH ao ssh-agent. O ssh-agent mantém suas chaves privadas descriptografadas na memória e assina solicitações de autenticação em seu nome, para que você precise digitar a frase-senha apenas uma vez por sessão.

Execute o comando a seguir para garantir que o ssh-agent esteja em execução:

Chave SSH no Linux

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

Se o ssh-agent estiver em execução, adicione a nova chave SSH ao agente SSH local executando o seguinte comando:

Chave SSH

ssh-add ~/.ssh/id_ed25519

(Nota: No macOS moderno (OpenSSH 8.8+), ssh-add -K está obsoleto. Em vez disso, adicione AddKeysToAgent yes ao arquivo ~/.ssh/config para persistir automaticamente as chaves no keychain.)

5. Copie a chave pública para o servidor remoto. Para usar a chave na autenticação, você deve adicioná-la ao arquivo ~/.ssh/authorized_keys do servidor remoto. Execute o seguinte comando a partir da sua máquina local:

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

6. Verifique a conexão. Teste se você consegue fazer login no servidor remoto usando sua nova chave:

ssh user@remote_host

Criar uma Chave SSH no Windows

Você precisa do Git Bash para criar uma chave SSH no sistema operacional Windows. Abra o Git Bash e execute o seguinte comando para gerar a chave:

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

Siga os mesmos prompts acima para definir o local do arquivo e a frase-senha. Após gerar a chave, copie-a para seu servidor remoto ou serviço de hospedagem Git usando o comando ssh-copy-id, ou colando o conteúdo de id_ed25519.pub nas configurações de chave SSH do serviço.

Adicionar sua Chave ao GitHub, GitLab ou Bitbucket

Um host Git não é um servidor SSH que você controla, portanto o ssh-copy-id não se aplica — em vez disso, você cola a chave pública na interface web. Imprima a chave pública e copie-a:

cat ~/.ssh/id_ed25519.pub

A saída é uma única linha que começa com ssh-ed25519 e termina com o comentário que você definiu:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... [email protected]

Copie essa linha inteira e adicione-a nas configurações de chave SSH da sua conta (no GitHub: Settings → SSH and GPG keys → New SSH key). Em seguida, verifique a conexão:

ssh -T [email protected]

Uma primeira conexão bem-sucedida pede que você confirme a impressão digital do host e o cumprimenta pelo nome de usuário — ela não abre um shell, o que é esperado para o GitHub.

Assim que a chave estiver registrada, altere seu remoto para a URL SSH para que os pushes a utilizem:

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

Consulte Git Remote para gerenciar URLs remotas e Git Push para enviar seus commits.

Problemas Comuns e Dicas

• Permission denied (publickey) geralmente significa que o host não possui uma chave pública correspondente, ou que o agente não contém sua chave privada. Execute ssh-add -l para listar as chaves carregadas e adicione a sua novamente se necessário.
• Reutilize uma chave em vários hosts. Um único par de chaves pode autenticar em muitos servidores; você não precisa de uma nova chave por projeto. Gere uma chave separada apenas quando quiser isolar o acesso.
• Faça backup das suas chaves, não apenas dos seus repositórios. Perder ~/.ssh/id_ed25519 significa regenerar e recadastrar em todos os lugares.
• As chaves SSH autenticam conexões; se você também quiser comprovar quem foi o autor de um commit, esse é um mecanismo separado — consulte Signing Commits. Para a configuração inicial, consulte Install Git e Git Config.

Prática