1.\" $OpenBSD: ssh-agent.1,v 1.9 2000/01/22 02:17:50 aaron Exp $ 2.\" 3.\" -*- nroff -*- 4.\" 5.\" ssh-agent.1 6.\" 7.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 8.\" 9.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 10.\" All rights reserved 11.\" 12.\" Created: Sat Apr 23 20:10:43 1995 ylo 13.\" 14.Dd September 25, 1999 15.Dt SSH-AGENT 1 16.Os 17.Sh NAME 18.Nm ssh-agent 19.Nd authentication agent 20.Sh SYNOPSIS 21.Nm ssh-agent 22.Op Fl c Li | Fl s 23.Op Fl k 24.Oo 25.Ar command 26.Op Ar args ... 27.Oc 28.Sh DESCRIPTION 29.Nm 30is a program to hold authentication private keys. The 31idea is that 32.Nm 33is started in the beginning of an X-session or a login session, and 34all other windows or programs are started as clients to the ssh-agent 35program. Through use of environment variables the agent can be located 36and automatically used for RSA authentication when logging in to other 37machines using 38.Xr ssh 1 . 39.Pp 40The options are as follows: 41.Bl -tag -width Ds 42.It Fl c 43Generate C-shell commands on 44.Dv stdout . 45This is the default if 46.Ev SHELL 47looks like it's a csh style of shell. 48.It Fl s 49Generate Bourne shell commands on 50.Dv stdout . 51This is the default if 52.Ev SHELL 53does not look like it's a csh style of shell. 54.It Fl k 55Kill the current agent (given by the 56.Ev SSH_AGENT_PID 57environment variable). 58.El 59.Pp 60If a commandline is given, this is executed as a subprocess of the agent. 61When the command dies, so does the agent. 62.Pp 63The agent initially does not have any private keys. Keys are added 64using 65.Xr ssh-add 1 . 66When executed without arguments, 67.Xr ssh-add 1 68adds the 69.Pa $HOME/.ssh/identity 70file. If the identity has a passphrase, 71.Xr ssh-add 1 72asks for the passphrase (using a small X11 application if running 73under X11, or from the terminal if running without X). It then sends 74the identity to the agent. Several identities can be stored in the 75agent; the agent can automatically use any of these identities. 76.Ic ssh-add -l 77displays the identities currently held by the agent. 78.Pp 79The idea is that the agent is run in the user's local PC, laptop, or 80terminal. Authentication data need not be stored on any other 81machine, and authentication passphrases never go over the network. 82However, the connection to the agent is forwarded over SSH 83remote logins, and the user can thus use the privileges given by the 84identities anywhere in the network in a secure way. 85.Pp 86There are two main ways to get an agent setup: Either you let the agent 87start a new subcommand into which some environment variables are exported, or 88you let the agent print the needed shell commands (either 89.Xr sh 1 90or 91.Xr csh 1 92syntax can be generated) which can be evalled in the calling shell. 93Later 94.Xr ssh 1 95look at these variables and use them to establish a connection to the agent. 96.Pp 97A unix-domain socket is created 98.Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> , 99and the name of this socket is stored in the 100.Ev SSH_AUTH_SOCK 101environment 102variable. The socket is made accessible only to the current user. 103This method is easily abused by root or another instance of the same 104user. 105.Pp 106The 107.Ev SSH_AGENT_PID 108environment variable holds the agent's PID. 109.Pp 110The agent exits automatically when the command given on the command 111line terminates. 112.Sh FILES 113.Bl -tag -width Ds 114.It Pa $HOME/.ssh/identity 115Contains the RSA authentication identity of the user. This file 116should not be readable by anyone but the user. It is possible to 117specify a passphrase when generating the key; that passphrase will be 118used to encrypt the private part of this file. This file 119is not used by 120.Nm 121but is normally added to the agent using 122.Xr ssh-add 1 123at login time. 124.It Pa /tmp/ssh-XXXX/agent.<pid> , 125Unix-domain sockets used to contain the connection to the 126authentication agent. These sockets should only be readable by the 127owner. The sockets should get automatically removed when the agent 128exits. 129.Sh AUTHOR 130Tatu Ylonen <ylo@cs.hut.fi> 131.Pp 132OpenSSH 133is a derivative of the original (free) ssh 1.2.12 release, but with bugs 134removed and newer features re-added. Rapidly after the 1.2.12 release, 135newer versions bore successively more restrictive licenses. This version 136of OpenSSH 137.Bl -bullet 138.It 139has all components of a restrictive nature (i.e., patents, see 140.Xr ssl 8 ) 141directly removed from the source code; any licensed or patented components 142are chosen from 143external libraries. 144.It 145has been updated to support ssh protocol 1.5. 146.It 147contains added support for 148.Xr kerberos 8 149authentication and ticket passing. 150.It 151supports one-time password authentication with 152.Xr skey 1 . 153.El 154.Pp 155The libraries described in 156.Xr ssl 8 157are required for proper operation. 158.Sh SEE ALSO 159.Xr ssh 1 , 160.Xr ssh-add 1 , 161.Xr ssh-keygen 1 , 162.Xr sshd 8 , 163.Xr ssl 8 164