Annotation of src/crypto/external/bsd/openssh/dist/ssh-agent.1, Revision 1.1.1.3
1.1 christos 1: .\" $NetBSD$
1.1.1.3 ! adam 2: .\" $OpenBSD: ssh-agent.1,v 1.50 2010/01/17 21:49:09 tedu Exp $
1.1 christos 3: .\"
4: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
5: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
6: .\" All rights reserved
7: .\"
8: .\" As far as I am concerned, the code I have written for this software
9: .\" can be used freely for any purpose. Any derived versions of this
10: .\" software must be clearly marked as such, and if the derived work is
11: .\" incompatible with the protocol description in the RFC file, it must be
12: .\" called by a name other than "ssh" or "Secure Shell".
13: .\"
14: .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
15: .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
16: .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
17: .\"
18: .\" Redistribution and use in source and binary forms, with or without
19: .\" modification, are permitted provided that the following conditions
20: .\" are met:
21: .\" 1. Redistributions of source code must retain the above copyright
22: .\" notice, this list of conditions and the following disclaimer.
23: .\" 2. Redistributions in binary form must reproduce the above copyright
24: .\" notice, this list of conditions and the following disclaimer in the
25: .\" documentation and/or other materials provided with the distribution.
26: .\"
27: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
36: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37: .\"
1.1.1.3 ! adam 38: .Dd $Mdocdate: January 17 2010 $
1.1 christos 39: .Dt SSH-AGENT 1
40: .Os
41: .Sh NAME
42: .Nm ssh-agent
43: .Nd authentication agent
44: .Sh SYNOPSIS
45: .Nm ssh-agent
46: .Op Fl c Li | Fl s
47: .Op Fl d
48: .Op Fl a Ar bind_address
49: .Op Fl t Ar life
50: .Op Ar command Op Ar arg ...
51: .Nm ssh-agent
52: .Op Fl c Li | Fl s
53: .Fl k
54: .Sh DESCRIPTION
55: .Nm
56: is a program to hold private keys used for public key authentication
57: (RSA, DSA).
58: The idea is that
59: .Nm
60: is started in the beginning of an X-session or a login session, and
61: all other windows or programs are started as clients to the ssh-agent
62: program.
63: Through use of environment variables the agent can be located
64: and automatically used for authentication when logging in to other
65: machines using
66: .Xr ssh 1 .
67: .Pp
68: The options are as follows:
69: .Bl -tag -width Ds
70: .It Fl a Ar bind_address
1.1.1.3 ! adam 71: Bind the agent to the
! 72: .Ux Ns -domain
! 73: socket
1.1 christos 74: .Ar bind_address .
75: The default is
76: .Pa /tmp/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
77: .It Fl c
78: Generate C-shell commands on
79: .Dv stdout .
80: This is the default if
81: .Ev SHELL
82: looks like it's a csh style of shell.
83: .It Fl d
84: Debug mode.
85: When this option is specified
86: .Nm
87: will not fork.
88: .It Fl k
89: Kill the current agent (given by the
90: .Ev SSH_AGENT_PID
91: environment variable).
92: .It Fl s
93: Generate Bourne shell commands on
94: .Dv stdout .
95: This is the default if
96: .Ev SHELL
97: does not look like it's a csh style of shell.
98: .It Fl t Ar life
99: Set a default value for the maximum lifetime of identities added to the agent.
100: The lifetime may be specified in seconds or in a time format specified in
101: .Xr sshd_config 5 .
102: A lifetime specified for an identity with
103: .Xr ssh-add 1
104: overrides this value.
105: Without this option the default maximum lifetime is forever.
106: .El
107: .Pp
108: If a commandline is given, this is executed as a subprocess of the agent.
109: When the command dies, so does the agent.
110: .Pp
111: The agent initially does not have any private keys.
112: Keys are added using
113: .Xr ssh-add 1 .
114: When executed without arguments,
115: .Xr ssh-add 1
116: adds the files
117: .Pa ~/.ssh/id_rsa ,
118: .Pa ~/.ssh/id_dsa
119: and
120: .Pa ~/.ssh/identity .
121: If the identity has a passphrase,
122: .Xr ssh-add 1
1.1.1.3 ! adam 123: asks for the passphrase on the terminal if it has one or from a small X11
! 124: program if running under X11.
! 125: If neither of these is the case then the authentication will fail.
1.1 christos 126: It then sends the identity to the agent.
127: Several identities can be stored in the
128: agent; the agent can automatically use any of these identities.
129: .Ic ssh-add -l
130: displays the identities currently held by the agent.
131: .Pp
132: The idea is that the agent is run in the user's local PC, laptop, or
133: terminal.
134: Authentication data need not be stored on any other
135: machine, and authentication passphrases never go over the network.
136: However, the connection to the agent is forwarded over SSH
137: remote logins, and the user can thus use the privileges given by the
138: identities anywhere in the network in a secure way.
139: .Pp
140: There are two main ways to get an agent set up:
141: The first is that the agent starts a new subcommand into which some environment
142: variables are exported, eg
143: .Cm ssh-agent xterm & .
144: The second is that the agent prints the needed shell commands (either
145: .Xr sh 1
146: or
147: .Xr csh 1
1.1.1.2 christos 148: syntax can be generated) which can be evaluated in the calling shell, eg
1.1 christos 149: .Cm eval `ssh-agent -s`
150: for Bourne-type shells such as
151: .Xr sh 1
152: or
153: .Xr ksh 1
154: and
155: .Cm eval `ssh-agent -c`
156: for
157: .Xr csh 1
158: and derivatives.
159: .Pp
160: Later
161: .Xr ssh 1
162: looks at these variables and uses them to establish a connection to the agent.
163: .Pp
164: The agent will never send a private key over its request channel.
165: Instead, operations that require a private key will be performed
166: by the agent, and the result will be returned to the requester.
167: This way, private keys are not exposed to clients using the agent.
168: .Pp
1.1.1.3 ! adam 169: A
! 170: .Ux Ns -domain
! 171: socket is created and the name of this socket is stored in the
1.1 christos 172: .Ev SSH_AUTH_SOCK
173: environment
174: variable.
175: The socket is made accessible only to the current user.
176: This method is easily abused by root or another instance of the same
177: user.
178: .Pp
179: The
180: .Ev SSH_AGENT_PID
181: environment variable holds the agent's process ID.
182: .Pp
183: The agent exits automatically when the command given on the command
184: line terminates.
185: .Sh FILES
186: .Bl -tag -width Ds
187: .It Pa ~/.ssh/identity
188: Contains the protocol version 1 RSA authentication identity of the user.
189: .It Pa ~/.ssh/id_dsa
190: Contains the protocol version 2 DSA authentication identity of the user.
191: .It Pa ~/.ssh/id_rsa
192: Contains the protocol version 2 RSA authentication identity of the user.
193: .It Pa /tmp/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt
1.1.1.3 ! adam 194: .Ux Ns -domain
! 195: sockets used to contain the connection to the authentication agent.
1.1 christos 196: These sockets should only be readable by the owner.
197: The sockets should get automatically removed when the agent exits.
198: .El
199: .Sh SEE ALSO
200: .Xr ssh 1 ,
201: .Xr ssh-add 1 ,
202: .Xr ssh-keygen 1 ,
203: .Xr sshd 8
204: .Sh AUTHORS
205: OpenSSH is a derivative of the original and free
206: ssh 1.2.12 release by Tatu Ylonen.
207: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
208: Theo de Raadt and Dug Song
209: removed many bugs, re-added newer features and
210: created OpenSSH.
211: Markus Friedl contributed the support for SSH
212: protocol versions 1.5 and 2.0.
CVSweb <webmaster@jp.NetBSD.org>
![[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 [cvs.NetBSD.org] / src / crypto / external / bsd / openssh / dist