ssh-agent e ssh-add, na prática: pare de digitar sua frase-senha

O ssh-agent é um programa em segundo plano que mantém as suas chaves privadas desbloqueadas na memória e assina desafios de autenticação com elas, para que você digite a frase-senha de uma chave uma vez por sessão, em vez de uma vez por conexão. O ssh-add é o comando que carrega chaves nele.

Você fez a coisa certa e colocou uma frase-senha na sua chave SSH — e agora está digitando-a pela quinta vez antes do almoço. A solução existe há décadas: o agente SSH. Desbloqueie a chave uma vez, e toda conexão depois disso autentica em silêncio. A ressalva é que esse “uma vez” só funciona se o agente estiver realmente rodando, o seu shell conseguir encontrá-lo e a chave estiver carregada — três coisas separadas, cada uma com o próprio jeito de falhar. Este é o guia prático: iniciar o agente em cada sistema operacional, operá-lo com o ssh-add, tornar tudo automático e decodificar os dois erros que respondem por quase todo problema de agente.

O que o agente é, em um parágrafo

O ssh-agent é um pequeno processo em segundo plano que mantém as suas chaves privadas descriptografadas na memória — nunca no disco. Quando um servidor te desafia, o ssh entrega o desafio ao agente, o agente o assina com a chave que está na memória, e só a assinatura volta — a chave em si nunca deixa o agente, nunca passa pela rede e continua criptografada no disco. Um único pedido de frase-senha para carregar a chave, depois toda conexão posterior é servida da memória. Esse é o modelo mental inteiro: o agente é um serviço de assinatura, não um cofre de chaves do qual alguém lê — ele guarda o segredo e só entrega assinaturas. (Essa única propriedade também é a ressalva de segurança, e ela ganha a própria seção no fim.)

No Windows? Leia antes o guia do Windows

Se você chegou aqui por causa de error connecting to agent: No such file or directory, essa mensagem é específica do Windows: ela vem do ssh do Git Bash / MSYS2, e as correções também — o serviço OpenSSH Authentication Agent, o próprio agente do Git Bash e o erro 1058. Está tudo em ssh-agent no Windows. Tudo o que vem abaixo é o fluxo multiplataforma do ssh-agent e do ssh-add, e os erros que ele decifra são os do próprio cliente OpenSSH: Could not open a connection to your authentication agent e The agent has no identities.

Iniciando o agente, por sistema operacional

Linux — eval "$(ssh-agent -s)"

Em um login de desktop você quase com certeza já tem um agente — seja um serviço de usuário do systemd, seja o GNOME Keyring fazendo o papel — com o SSH_AUTH_SOCK exportado para a sua sessão inteira. Teste com ssh-add -l. Se nada responder (comum em um login SSH pelado, em contêineres ou em servidores mínimos), inicie um à mão:

eval "$(ssh-agent -s)"

O eval importa. O ssh-agent -s só imprime as variáveis SSH_AUTH_SOCK e SSH_AGENT_PID; é o eval que as define no seu shell atual, para que o ssh encontre o socket. Rodar o ssh-agent pelado e se perguntar por que nada mudou é o jeito mais comum de “iniciar” um agente que nenhuma ferramenta enxerga.

macOS — o launchd o roda por você

O launchd roda um agente por você desde o login — não há nada para iniciar. A vantagem específica do macOS é a integração com o Keychain, mais abaixo.

Inicie o ssh-agent no Windows

O Windows moderno traz um serviço OpenSSH Authentication Agent, mas ele vem com início manual e não roda por padrão. Ative-o uma vez, a partir de um PowerShell elevado:

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

Depois disso, o ssh-add funciona em qualquer terminal — PowerShell, cmd ou o cliente OpenSSH do Windows dentro do Git Bash — e o agente sobrevive às reinicializações. Uma armadilha: o Git for Windows traz o próprio ssh e ssh-agent, e dentro do Git Bash o ssh no seu PATH pode ser aquele, falando com um agente separado. Se o ssh-add -l discordar entre o Git Bash e o PowerShell, aponte o Git para o cliente do sistema, para que os dois compartilhem um agente:

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

O passo a passo completo — o serviço, o Git Bash e o carregamento de chaves no login — está em ssh-agent no Windows.

Operando com o ssh-add

Carregar uma chave: ssh-add ~/.ssh/id_ed25519

ssh-add                          # load the default keys (id_ed25519, id_rsa, …)
ssh-add ~/.ssh/id_ed25519        # load a specific key (prompts for the passphrase once)

Sem um caminho, o ssh-add carrega os nomes de chave padrão de ~/.ssh; dê um caminho para carregar uma chave específica. De qualquer forma, ele pede a frase-senha uma vez e depois mantém a chave descriptografada na memória.

Listar o que está carregado: ssh-add -l

ssh-add -l                       # list fingerprints of loaded keys
ssh-add -L                       # print the full public keys
ssh-add -d ~/.ssh/id_ed25519     # remove one key
ssh-add -D                       # remove all keys

O ssh-add -l é o primeiro diagnóstico para qualquer problema de autenticação: se a chave que você espera não está nessa lista, o agente não consegue assinar com ela, por mais que todo o resto pareça certo.

Defina um tempo de expiração para o ssh-agent: ssh-add -t

Vale transformar duas flags em hábito:

• -t define um tempo de vida. ssh-add -t 3600 ~/.ssh/id_ed25519 carrega a chave por uma hora; depois disso o agente a esquece e o próximo uso pede de novo. Uma chave que fica desbloqueada na memória por um uptime de três semanas é uma chave utilizável muito tempo depois de você parar de pensar nela.
• -c exige confirmação. Cada pedido de assinatura faz surgir um prompt local antes de o agente responder. Um pouco irritante, exatamente o certo para chaves de alto valor.

Torne automático: AddKeysToAgent

O ritual manual do ssh-add desaparece com uma linha no ~/.ssh/config (em inglês):

Host *
    AddKeysToAgent yes

Agora o primeiro ssh que precisa de uma chave pede a frase-senha uma vez e carrega a chave no agente como efeito colateral. Nenhum comando separado para lembrar — o prompt simplesmente para de se repetir. Você pode defini-lo com um tempo de vida também (AddKeysToAgent 1h) para ter o comportamento do -t sem a flag.

macOS: sobreviva às reinicializações com o Keychain. Por padrão, o agente esquece as chaves quando reinicia. O macOS pode guardar a frase-senha no seu keychain de login, para que as chaves recarreguem sem redigitar:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

e no ~/.ssh/config:

Host *
    AddKeysToAgent yes
    UseKeychain yes

Depois disso, a pergunta da frase-senha é respondida pelo Keychain no login e você nunca mais a vê — enquanto o arquivo da chave no disco continua criptografado.

Os dois erros em que todo mundo esbarra

Could not open a connection to your authentication agent — o ssh-add não encontra um agente. Ou nenhum está rodando, ou um está rodando mas este shell não tem o SSH_AUTH_SOCK definido. A correção é o início por sistema operacional acima: a linha eval "$(ssh-agent -s)" no Linux (verifique antes se a sua sessão de desktop já fornece um — iniciar um segundo agente por terminal só espalha as chaves carregadas entre processos), o início do serviço no Windows. Você também vai encontrar isso em jobs do cron e em CI, onde nenhuma sessão de login jamais exportou a variável.

The agent has no identities. — o problema oposto: o agente está bem, mas nada foi carregado. Faça ssh-add da sua chave. Se ela estava carregada e sumiu, um tempo de vida do -t expirou ou o agente reiniciou — que é exatamente para isso que servem o AddKeysToAgent yes e o Keychain do macOS.

E o terceiro caso: o agente parece perfeito — o ssh-add -l mostra a chave — mas o servidor ainda diz Permission denied (publickey). Isso já não é problema de agente; percorra a lista de verificação do publickey — usuário errado, chave errada oferecida, permissões de authorized_keys.

Um agente desbloqueado é uma credencial viva

O agente nunca vaza a chave — mas o socket é um oráculo de assinatura: ele assina para quem quer que o alcance, e nunca pergunta quem está pedindo. Na sua própria máquina, tudo bem — o socket fica em um diretório privado por usuário que só você consegue ler. O perigo é o formato do confused deputy (vice confuso): quando o socket passa a ser alcançável por algo que você não pretendia — um agente encaminhado em um bastion compartilhado, ou um processo rodando como o seu usuário em que você não confia —, essa coisa pode se autenticar como você em todo servidor que as suas chaves alcançam, sem nunca ver a chave. A chave nunca vazar é só metade da garantia; controlar quem pode usá-la é a outra metade, e é por isso que a higiene do agente vale o pequeno esforço.

• Dê um tempo de vida às chaves (-t, ou um tempo de vida no AddKeysToAgent) para que um agente ocioso esfrie sozinho.
• Bloqueie o agente ao se afastar: ssh-add -x o tranca atrás de uma senha, ssh-add -X destranca; ssh-add -D simplesmente descarta tudo.
• Use -c para as chaves que chegam à produção.
• Não encaminhe o agente por padrão. O ssh -A — o encaminhamento do agente SSH (ssh agent forwarding) — expõe o uso ao vivo das suas chaves no host remoto, então qualquer um com root lá pode assinar como você durante toda a sua sessão. Esse merece uma leitura própria: o encaminhamento do agente SSH é conveniente e perigoso (em inglês).

Como o Termalin lida com isso

O Termalin traz todo esse fluxo embutido, com as arestas aparadas. O agente de chaves dele desbloqueia as suas chaves uma vez e assina em seu nome — sem serviço do sistema para ativar, sem linha de eval, sem socket por shell para perder. O cache da frase-senha vem com um tempo para voltar a bloquear por padrão, que é o hábito do ssh-add -t cumprido por ele, em vez de lembrado por você. E como ele fala o protocolo padrão do ssh-agent, o git e as suas ferramentas de linha de comando atuais assinam por ele sem mudança — ele substitui o ritual, não a sua toolchain.

---

O Termalin é um cliente SSH gratuito e multiplataforma cujo agente integrado desbloqueia as suas chaves uma vez e volta a bloquear por um temporizador — baixe o Termalin, ou leia como ele cuida das suas chaves com segurança.