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