Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.5
1.1 deraadt 1: .\" -*- nroff -*-
2: .\"
3: .\" ssh-agent.1
4: .\"
5: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
6: .\"
7: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
8: .\" All rights reserved
9: .\"
10: .\" Created: Sat Apr 23 20:10:43 1995 ylo
11: .\"
1.5 ! markus 12: .\" $Id: ssh-agent.1,v 1.4 1999/10/14 18:17:42 markus Exp $
1.1 deraadt 13: .\"
1.2 deraadt 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: .Ar command
23: .Sh DESCRIPTION
24: .Nm
1.1 deraadt 25: is a program to hold authentication private keys. The
26: idea is that
1.2 deraadt 27: .Nm
1.1 deraadt 28: is started in the beginning of an X-session or a login session, and
29: all other windows or programs are started as children of the ssh-agent
30: program (the
1.2 deraadt 31: .Ar command
1.1 deraadt 32: normally starts X or is the user shell). Programs started under
33: the agent inherit a connection to the agent, and the agent is
34: automatically used for RSA authentication when logging to other
35: machines using
1.2 deraadt 36: .Xr ssh 1 .
37: .Pp
1.1 deraadt 38: The agent initially does not have any private keys. Keys are added
39: using
1.2 deraadt 40: .Xr ssh-add 1 .
1.1 deraadt 41: When executed without arguments,
1.2 deraadt 42: .Xr ssh-add 1
1.1 deraadt 43: adds the
1.2 deraadt 44: .Pa $HOME/.ssh/identity
1.1 deraadt 45: file. If the identity has a passphrase,
1.2 deraadt 46: .Xr ssh-add 1
1.1 deraadt 47: asks for the passphrase (using a small X11 application if running
48: under X11, or from the terminal if running without X). It then sends
49: the identity to the agent. Several identities can be stored in the
50: agent; the agent can automatically use any of these identities.
1.2 deraadt 51: .Ic ssh-add -l
1.1 deraadt 52: displays the identities currently held by the agent.
1.2 deraadt 53: .Pp
1.1 deraadt 54: The idea is that the agent is run in the user's local PC, laptop, or
55: terminal. Authentication data need not be stored on any other
56: machine, and authentication passphrases never go over the network.
1.2 deraadt 57: However, the connection to the agent is forwarded over SSH
1.1 deraadt 58: remote logins, and the user can thus use the privileges given by the
59: identities anywhere in the network in a secure way.
1.2 deraadt 60: .Pp
1.4 markus 61: A connection to the agent is inherited by child programs:
62: A unix-domain socket is created
63: .Pq Pa /tmp/ssh-XXXX/agent.<pid> ,
1.2 deraadt 64: and the name of this socket is stored in the
1.5 ! markus 65: .Ev SSH_AUTH_SOCK
1.1 deraadt 66: environment
67: variable. The socket is made accessible only to the current user.
68: This method is easily abused by root or another instance of the same
1.4 markus 69: user.
1.2 deraadt 70: .Pp
1.1 deraadt 71: The agent exits automatically when the command given on the command
72: line terminates.
1.2 deraadt 73: .Sh FILES
74: .Bl -tag -width Ds
75: .It Pa $HOME/.ssh/identity
1.1 deraadt 76: Contains the RSA authentication identity of the user. This file
77: should not be readable by anyone but the user. It is possible to
78: specify a passphrase when generating the key; that passphrase will be
79: used to encrypt the private part of this file. This file
80: is not used by
1.2 deraadt 81: .Nm
1.1 deraadt 82: but is normally added to the agent using
1.2 deraadt 83: .Xr ssh-add 1
1.1 deraadt 84: at login time.
1.4 markus 85: .It Pa /tmp/ssh-XXXX/agent.<pid> ,
1.1 deraadt 86: Unix-domain sockets used to contain the connection to the
87: authentication agent. These sockets should only be readable by the
88: owner. The sockets should get automatically removed when the agent
89: exits.
1.2 deraadt 90: .Sh AUTHOR
1.1 deraadt 91: Tatu Ylonen <ylo@cs.hut.fi>
1.3 deraadt 92: .Pp
93: This version of
94: .Nm
95: is a derivative of the original 1.2.12 release, but with bugs removed and
96: newer features re-added. Rapidly after the 1.2.12 release, newer versions
97: bore successively more restrictive licenses. In this version, all components
98: of a restrictive nature (ie. patents) have been directly removed from the
99: source code; any licensed or patented components are chosen from external
100: libraries. The libraries described in
101: .Xr ssl 8
102: are required for proper operation.
1.2 deraadt 103: .Sh SEE ALSO
104: .Xr ssh 1 ,
105: .Xr ssh-add 1 ,
106: .Xr ssh-keygen 1 ,
1.3 deraadt 107: .Xr sshd 8 ,
108: .Xr ssl 8