xref: /freebsd/crypto/openssh/ssh-agent.1 (revision ca86bcf2531c7b149c95244a67853d44323e7855)
1*ca86bcf2SDag-Erling Smørgrav.\" $OpenBSD: ssh-agent.1,v 1.64 2016/11/30 06:54:26 jmc Exp $
27aee6ffeSDag-Erling Smørgrav.\" $FreeBSD$
3511b41d2SMark Murray.\"
4511b41d2SMark Murray.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
5511b41d2SMark Murray.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
6511b41d2SMark Murray.\"                    All rights reserved
7511b41d2SMark Murray.\"
8b66f2d16SKris Kennaway.\" As far as I am concerned, the code I have written for this software
9b66f2d16SKris Kennaway.\" can be used freely for any purpose.  Any derived versions of this
10b66f2d16SKris Kennaway.\" software must be clearly marked as such, and if the derived work is
11b66f2d16SKris Kennaway.\" incompatible with the protocol description in the RFC file, it must be
12b66f2d16SKris Kennaway.\" called by a name other than "ssh" or "Secure Shell".
13b66f2d16SKris Kennaway.\"
14b66f2d16SKris Kennaway.\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
15b66f2d16SKris Kennaway.\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
16b66f2d16SKris Kennaway.\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
17b66f2d16SKris Kennaway.\"
18b66f2d16SKris Kennaway.\" Redistribution and use in source and binary forms, with or without
19b66f2d16SKris Kennaway.\" modification, are permitted provided that the following conditions
20b66f2d16SKris Kennaway.\" are met:
21b66f2d16SKris Kennaway.\" 1. Redistributions of source code must retain the above copyright
22b66f2d16SKris Kennaway.\"    notice, this list of conditions and the following disclaimer.
23b66f2d16SKris Kennaway.\" 2. Redistributions in binary form must reproduce the above copyright
24b66f2d16SKris Kennaway.\"    notice, this list of conditions and the following disclaimer in the
25b66f2d16SKris Kennaway.\"    documentation and/or other materials provided with the distribution.
26b66f2d16SKris Kennaway.\"
27b66f2d16SKris Kennaway.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28b66f2d16SKris Kennaway.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29b66f2d16SKris Kennaway.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30b66f2d16SKris Kennaway.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31b66f2d16SKris Kennaway.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32b66f2d16SKris Kennaway.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33b66f2d16SKris Kennaway.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34b66f2d16SKris Kennaway.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35b66f2d16SKris Kennaway.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
36b66f2d16SKris Kennaway.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37511b41d2SMark Murray.\"
38*ca86bcf2SDag-Erling Smørgrav.Dd $Mdocdate: November 30 2016 $
39511b41d2SMark Murray.Dt SSH-AGENT 1
40511b41d2SMark Murray.Os
41511b41d2SMark Murray.Sh NAME
42511b41d2SMark Murray.Nm ssh-agent
43511b41d2SMark Murray.Nd authentication agent
44511b41d2SMark Murray.Sh SYNOPSIS
45511b41d2SMark Murray.Nm ssh-agent
464a421b63SDag-Erling Smørgrav.Op Fl c | s
47acc1a9efSDag-Erling Smørgrav.Op Fl \&Ddx
48d4af9e69SDag-Erling Smørgrav.Op Fl a Ar bind_address
49bc5531deSDag-Erling Smørgrav.Op Fl E Ar fingerprint_hash
50*ca86bcf2SDag-Erling Smørgrav.Op Fl P Ar pkcs11_whitelist
51d4af9e69SDag-Erling Smørgrav.Op Fl t Ar life
52d4af9e69SDag-Erling Smørgrav.Op Ar command Op Ar arg ...
531e8db6e2SBrian Feldman.Nm ssh-agent
544a421b63SDag-Erling Smørgrav.Op Fl c | s
551e8db6e2SBrian Feldman.Fl k
56511b41d2SMark Murray.Sh DESCRIPTION
57511b41d2SMark Murray.Nm
58b66f2d16SKris Kennawayis a program to hold private keys used for public key authentication
59bc5531deSDag-Erling Smørgrav(RSA, DSA, ECDSA, Ed25519).
60511b41d2SMark Murray.Nm
61a0ee8cc6SDag-Erling Smørgravis usually started in the beginning of an X-session or a login session, and
62511b41d2SMark Murrayall other windows or programs are started as clients to the ssh-agent
63a8f6863aSKris Kennawayprogram.
64a8f6863aSKris KennawayThrough use of environment variables the agent can be located
65b66f2d16SKris Kennawayand automatically used for authentication when logging in to other
66511b41d2SMark Murraymachines using
67511b41d2SMark Murray.Xr ssh 1 .
68511b41d2SMark Murray.Pp
69a0ee8cc6SDag-Erling SmørgravThe agent initially does not have any private keys.
70a0ee8cc6SDag-Erling SmørgravKeys are added using
71acc1a9efSDag-Erling Smørgrav.Xr ssh 1
72acc1a9efSDag-Erling Smørgrav(see
73acc1a9efSDag-Erling Smørgrav.Cm AddKeysToAgent
74acc1a9efSDag-Erling Smørgravin
75acc1a9efSDag-Erling Smørgrav.Xr ssh_config 5
76acc1a9efSDag-Erling Smørgravfor details)
77acc1a9efSDag-Erling Smørgravor
78a0ee8cc6SDag-Erling Smørgrav.Xr ssh-add 1 .
79a0ee8cc6SDag-Erling SmørgravMultiple identities may be stored in
80a0ee8cc6SDag-Erling Smørgrav.Nm
81a0ee8cc6SDag-Erling Smørgravconcurrently and
82a0ee8cc6SDag-Erling Smørgrav.Xr ssh 1
83a0ee8cc6SDag-Erling Smørgravwill automatically use them if present.
84a0ee8cc6SDag-Erling Smørgrav.Xr ssh-add 1
85a0ee8cc6SDag-Erling Smørgravis also used to remove keys from
86a0ee8cc6SDag-Erling Smørgrav.Nm
87a0ee8cc6SDag-Erling Smørgravand to query the keys that are held in one.
88a0ee8cc6SDag-Erling Smørgrav.Pp
89511b41d2SMark MurrayThe options are as follows:
90511b41d2SMark Murray.Bl -tag -width Ds
91545d5ecaSDag-Erling Smørgrav.It Fl a Ar bind_address
92b15c8340SDag-Erling SmørgravBind the agent to the
93b15c8340SDag-Erling Smørgrav.Ux Ns -domain
94b15c8340SDag-Erling Smørgravsocket
95545d5ecaSDag-Erling Smørgrav.Ar bind_address .
96545d5ecaSDag-Erling SmørgravThe default is
974a421b63SDag-Erling Smørgrav.Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
98511b41d2SMark Murray.It Fl c
99511b41d2SMark MurrayGenerate C-shell commands on
100511b41d2SMark Murray.Dv stdout .
101511b41d2SMark MurrayThis is the default if
102511b41d2SMark Murray.Ev SHELL
103511b41d2SMark Murraylooks like it's a csh style of shell.
104557f75e5SDag-Erling Smørgrav.It Fl D
105557f75e5SDag-Erling SmørgravForeground mode.
106557f75e5SDag-Erling SmørgravWhen this option is specified
107557f75e5SDag-Erling Smørgrav.Nm
108557f75e5SDag-Erling Smørgravwill not fork.
109d4af9e69SDag-Erling Smørgrav.It Fl d
110d4af9e69SDag-Erling SmørgravDebug mode.
111d4af9e69SDag-Erling SmørgravWhen this option is specified
112d4af9e69SDag-Erling Smørgrav.Nm
113557f75e5SDag-Erling Smørgravwill not fork and will write debug information to standard error.
114bc5531deSDag-Erling Smørgrav.It Fl E Ar fingerprint_hash
115bc5531deSDag-Erling SmørgravSpecifies the hash algorithm used when displaying key fingerprints.
116bc5531deSDag-Erling SmørgravValid options are:
117bc5531deSDag-Erling Smørgrav.Dq md5
118bc5531deSDag-Erling Smørgravand
119bc5531deSDag-Erling Smørgrav.Dq sha256 .
120bc5531deSDag-Erling SmørgravThe default is
121bc5531deSDag-Erling Smørgrav.Dq sha256 .
122d4af9e69SDag-Erling Smørgrav.It Fl k
123d4af9e69SDag-Erling SmørgravKill the current agent (given by the
124d4af9e69SDag-Erling Smørgrav.Ev SSH_AGENT_PID
125d4af9e69SDag-Erling Smørgravenvironment variable).
126*ca86bcf2SDag-Erling Smørgrav.It Fl P Ar pkcs11_whitelist
127*ca86bcf2SDag-Erling SmørgravSpecify a pattern-list of acceptable paths for PKCS#11 shared libraries
128*ca86bcf2SDag-Erling Smørgravthat may be added using the
129*ca86bcf2SDag-Erling Smørgrav.Fl s
130*ca86bcf2SDag-Erling Smørgravoption to
131*ca86bcf2SDag-Erling Smørgrav.Xr ssh-add 1 .
132*ca86bcf2SDag-Erling SmørgravThe default is to allow loading PKCS#11 libraries from
133*ca86bcf2SDag-Erling Smørgrav.Dq /usr/lib/*,/usr/local/lib/* .
134*ca86bcf2SDag-Erling SmørgravPKCS#11 libraries that do not match the whitelist will be refused.
135*ca86bcf2SDag-Erling SmørgravSee PATTERNS in
136*ca86bcf2SDag-Erling Smørgrav.Xr ssh_config 5
137*ca86bcf2SDag-Erling Smørgravfor a description of pattern-list syntax.
138511b41d2SMark Murray.It Fl s
139511b41d2SMark MurrayGenerate Bourne shell commands on
140511b41d2SMark Murray.Dv stdout .
141511b41d2SMark MurrayThis is the default if
142511b41d2SMark Murray.Ev SHELL
143511b41d2SMark Murraydoes not look like it's a csh style of shell.
144d0c8c0bcSDag-Erling Smørgrav.It Fl t Ar life
145d0c8c0bcSDag-Erling SmørgravSet a default value for the maximum lifetime of identities added to the agent.
146d0c8c0bcSDag-Erling SmørgravThe lifetime may be specified in seconds or in a time format specified in
147021d409fSDag-Erling Smørgrav.Xr sshd_config 5 .
148d0c8c0bcSDag-Erling SmørgravA lifetime specified for an identity with
149d0c8c0bcSDag-Erling Smørgrav.Xr ssh-add 1
150d0c8c0bcSDag-Erling Smørgravoverrides this value.
151d0c8c0bcSDag-Erling SmørgravWithout this option the default maximum lifetime is forever.
152fceeafceSDag-Erling Smørgrav.It Fl x
153fceeafceSDag-Erling SmørgravExit after the last client has disconnected.
154511b41d2SMark Murray.El
155511b41d2SMark Murray.Pp
156511b41d2SMark MurrayIf a command line is given, this is executed as a subprocess of the agent.
157511b41d2SMark MurrayWhen the command dies, so does the agent.
158511b41d2SMark Murray.Pp
159511b41d2SMark MurrayThe idea is that the agent is run in the user's local PC, laptop, or
160a8f6863aSKris Kennawayterminal.
161a8f6863aSKris KennawayAuthentication data need not be stored on any other
162511b41d2SMark Murraymachine, and authentication passphrases never go over the network.
163511b41d2SMark MurrayHowever, the connection to the agent is forwarded over SSH
164511b41d2SMark Murrayremote logins, and the user can thus use the privileges given by the
165511b41d2SMark Murrayidentities anywhere in the network in a secure way.
166511b41d2SMark Murray.Pp
167a8f6863aSKris KennawayThere are two main ways to get an agent set up:
168d74d50a8SDag-Erling SmørgravThe first is that the agent starts a new subcommand into which some environment
169d74d50a8SDag-Erling Smørgravvariables are exported, eg
170d74d50a8SDag-Erling Smørgrav.Cm ssh-agent xterm & .
171d74d50a8SDag-Erling SmørgravThe second is that the agent prints the needed shell commands (either
172511b41d2SMark Murray.Xr sh 1
173511b41d2SMark Murrayor
174511b41d2SMark Murray.Xr csh 1
1757aee6ffeSDag-Erling Smørgravsyntax can be generated) which can be evaluated in the calling shell, eg
176d74d50a8SDag-Erling Smørgrav.Cm eval `ssh-agent -s`
177d74d50a8SDag-Erling Smørgravfor Bourne-type shells such as
178d74d50a8SDag-Erling Smørgrav.Xr sh 1
179d74d50a8SDag-Erling Smørgravor
180d74d50a8SDag-Erling Smørgrav.Xr ksh 1
181d74d50a8SDag-Erling Smørgravand
182d74d50a8SDag-Erling Smørgrav.Cm eval `ssh-agent -c`
183d74d50a8SDag-Erling Smørgravfor
184d74d50a8SDag-Erling Smørgrav.Xr csh 1
185d74d50a8SDag-Erling Smørgravand derivatives.
186d74d50a8SDag-Erling Smørgrav.Pp
187511b41d2SMark MurrayLater
188511b41d2SMark Murray.Xr ssh 1
1891e8db6e2SBrian Feldmanlooks at these variables and uses them to establish a connection to the agent.
190511b41d2SMark Murray.Pp
191ae1f160dSDag-Erling SmørgravThe agent will never send a private key over its request channel.
192ae1f160dSDag-Erling SmørgravInstead, operations that require a private key will be performed
193ae1f160dSDag-Erling Smørgravby the agent, and the result will be returned to the requester.
194ae1f160dSDag-Erling SmørgravThis way, private keys are not exposed to clients using the agent.
195ae1f160dSDag-Erling Smørgrav.Pp
196b15c8340SDag-Erling SmørgravA
197b15c8340SDag-Erling Smørgrav.Ux Ns -domain
198b15c8340SDag-Erling Smørgravsocket is created and the name of this socket is stored in the
199511b41d2SMark Murray.Ev SSH_AUTH_SOCK
200511b41d2SMark Murrayenvironment
201a8f6863aSKris Kennawayvariable.
202a8f6863aSKris KennawayThe socket is made accessible only to the current user.
203511b41d2SMark MurrayThis method is easily abused by root or another instance of the same
204511b41d2SMark Murrayuser.
205511b41d2SMark Murray.Pp
206511b41d2SMark MurrayThe
207511b41d2SMark Murray.Ev SSH_AGENT_PID
208ee21a45fSDag-Erling Smørgravenvironment variable holds the agent's process ID.
209511b41d2SMark Murray.Pp
210511b41d2SMark MurrayThe agent exits automatically when the command given on the command
211511b41d2SMark Murrayline terminates.
212511b41d2SMark Murray.Sh FILES
213511b41d2SMark Murray.Bl -tag -width Ds
214*ca86bcf2SDag-Erling Smørgrav.It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
215b15c8340SDag-Erling Smørgrav.Ux Ns -domain
216b15c8340SDag-Erling Smørgravsockets used to contain the connection to the authentication agent.
217a8f6863aSKris KennawayThese sockets should only be readable by the owner.
218a8f6863aSKris KennawayThe sockets should get automatically removed when the agent exits.
219b66f2d16SKris Kennaway.El
220d95e11bfSDag-Erling Smørgrav.Sh SEE ALSO
221d95e11bfSDag-Erling Smørgrav.Xr ssh 1 ,
222d95e11bfSDag-Erling Smørgrav.Xr ssh-add 1 ,
223d95e11bfSDag-Erling Smørgrav.Xr ssh-keygen 1 ,
224d95e11bfSDag-Erling Smørgrav.Xr sshd 8
2251e8db6e2SBrian Feldman.Sh AUTHORS
226*ca86bcf2SDag-Erling Smørgrav.An -nosplit
227*ca86bcf2SDag-Erling SmørgravOpenSSH is a derivative of the original and free ssh 1.2.12 release by
228*ca86bcf2SDag-Erling Smørgrav.An Tatu Ylonen .
229*ca86bcf2SDag-Erling Smørgrav.An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt
230*ca86bcf2SDag-Erling Smørgravand
231*ca86bcf2SDag-Erling Smørgrav.An Dug Song
232*ca86bcf2SDag-Erling Smørgravremoved many bugs, re-added newer features and created OpenSSH.
233*ca86bcf2SDag-Erling Smørgrav.An Markus Friedl
234*ca86bcf2SDag-Erling Smørgravcontributed the support for SSH protocol versions 1.5 and 2.0.
235