ssh-agent

Section: SSH (1)
Updated: November 8, 1995
SSH man page index Return to SSH FAQ

NAME

ssh-agent - authentication agent

SYNOPSIS

ssh-agent command

eval `ssh-agent[-k][-s][-c]`

DESCRIPTION

Ssh-agent is a program to hold authentication private keys. Theidea is thatssh-agentis started in the beginning of an X-session or a login session, andall other windows or programs are started as children of the ssh-agentprogram (thecommandnormally starts X or is the user shell). Programs started underthe agent inherit a connection to the agent, and the agent isautomatically used for RSA authentication when logging to othermachines usingssh.

If the ssh-agent is started without any arguments (no command) it willfork and start agent as background process. The agent also printscommand that can be evaluated in sh or csh like shells, that will settheSSH_AUTH_SOCKandSSH_AGENT_PIDenvironment variables.TheSSH_AGENT_PIDenvironment variable can be used to kill agent awaywhen it is no longer needed (you logout from X-session etc). If nooptions are given the ssh-agent uses SHELL environment variable thedetect what kind of shell you have (*csh or sh-style shell). The-coption will force csh-style shell, and-soption will force sh-style shell.

Note that in SysV variants (at least IRIX and Solaris)the environment variable SHELL might not contain theactual value of the shell executing the evaluation.If ALTSHELL is set to YES in /etc/default/login, the SHELLenvironment variable is set to the login shell of the user.

The-koption can be used to kill agent automatically. It kills the agent (ituses theSSH_AGENT_PIDto find it) and prints shell commands to stdout that will unset theSSH_AUTH_SOCKETandSSH_AGENT_PIDenviroment variables.

The agent initially does not have any private keys. Keys are addedusingssh-add.When executed without arguments, ssh-addadds the $HOME/.ssh/identityfile. If the identity has a passphrase, ssh-addasks for the passphrase (using a small X11 application if runningunder X11, or from the terminal if running without X). It then sendsthe identity to the agent. Several identities can be stored in theagent; the agent can automatically use any of these identities.Ssh-add -ldisplays the identities currently held by the agent.

The idea is that the agent is run in the user's local PC, laptop, orterminal. Authentication data need not be stored on any othermachine, and authentication passphrases never go over the network.However, the connection to the agent is forwarded oversshremote logins, and the user can thus use the privileges given by theidentities anywhere in the network in a secure way.

A connection to the agent is inherited by child programs. Aunix-domain socket is created(/tmp/ssh-$USER/ssh-<pid>-agent), where the %d is the processid of the listener (agent or sshd proxying the agent). The name ofthis socket is stored in theSSH_AUTH_SOCKenvironment variable. The socket is made accessible only to thecurrent user. This method is easily abused by root or anotherinstance of the same user. Older versions of ssh used inheritedfile descriptors for contacting the agent and used the unix-domainsockets in an incompatible way.

If the command is given as argument to ssh-agent the agent exitsautomatically when the command given on the command line terminates.The command is executed even if agent fails to start it's key-storingand challenge-processing services.

FILES

$HOME/.ssh/identity: Contains the RSA authentication identity of the user. This fileshould not be readable by anyone but the user. It is possible tospecify a passphrase when generating the key; that passphrase will beused to encrypt the private part of this file. This fileis not used byssh-agent,but is normally added to the agent usingssh-addat login time.
/tmp/ssh-$USER/ssh-<pid>-agent: Unix-domain sockets used to contain the connection to theauthentication agent. These sockets should only be readable by theowner. The sockets should get automatically removed when the agentexits. The parent directory of ssh-$USER must have it's sticky bitset.

AUTHOR