Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.3
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.3 ! deraadt 12: .\" $Id: ssh-agent.1,v 1.2 1999/09/26 22:30:06 deraadt 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.1 deraadt 61: A connection to the agent is inherited by child programs.
62: There are two alternative
63: methods for inheriting the agent. The preferred method is to have an
64: open file descriptor which is inherited, and have an environment
1.2 deraadt 65: variable
66: .Pq Ev SSH_AUTHENTICATION_FD
67: contain the number of this
1.1 deraadt 68: descriptor. This restricts access to the authentication agent to only
69: those programs that are siblings of the agent, and it is fairly
70: difficult even for root to get unauthorized access to the agent.
1.2 deraadt 71: .Pp
1.1 deraadt 72: On some machines, an alternative method is used. A unix-domain
1.2 deraadt 73: socket is created
74: .Pq Pa /tmp/ssh_agent.* ,
75: and the name of this socket is stored in the
76: .Ev SSH_AUTHENTICATION_SOCKET
1.1 deraadt 77: environment
78: variable. The socket is made accessible only to the current user.
79: This method is easily abused by root or another instance of the same
80: user. The socket is only used if ssh is unable to find a file
81: descriptor that would not be closed by shells.
1.2 deraadt 82: .Pp
1.1 deraadt 83: The agent exits automatically when the command given on the command
84: line terminates.
1.2 deraadt 85: .Sh FILES
86: .Bl -tag -width Ds
87: .It Pa $HOME/.ssh/identity
1.1 deraadt 88: Contains the RSA authentication identity of the user. This file
89: should not be readable by anyone but the user. It is possible to
90: specify a passphrase when generating the key; that passphrase will be
91: used to encrypt the private part of this file. This file
92: is not used by
1.2 deraadt 93: .Nm
1.1 deraadt 94: but is normally added to the agent using
1.2 deraadt 95: .Xr ssh-add 1
1.1 deraadt 96: at login time.
1.2 deraadt 97: .It Pa /tmp/ssh_agent.<pid>
1.1 deraadt 98: Unix-domain sockets used to contain the connection to the
99: authentication agent. These sockets should only be readable by the
100: owner. The sockets should get automatically removed when the agent
101: exits.
1.2 deraadt 102: .Sh AUTHOR
1.1 deraadt 103: Tatu Ylonen <ylo@cs.hut.fi>
1.3 ! deraadt 104: .Pp
! 105: This version of
! 106: .Nm
! 107: is a derivative of the original 1.2.12 release, but with bugs removed and
! 108: newer features re-added. Rapidly after the 1.2.12 release, newer versions
! 109: bore successively more restrictive licenses. In this version, all components
! 110: of a restrictive nature (ie. patents) have been directly removed from the
! 111: source code; any licensed or patented components are chosen from external
! 112: libraries. The libraries described in
! 113: .Xr ssl 8
! 114: are required for proper operation.
1.2 deraadt 115: .Sh SEE ALSO
116: .Xr ssh 1 ,
117: .Xr ssh-add 1 ,
118: .Xr ssh-keygen 1 ,
1.3 ! deraadt 119: .Xr sshd 8 ,
! 120: .Xr ssl 8
![[BACK]](/icons/back.gif){kind=icon}
Return to ssh-agent.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh