Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.67
1.66 jmc 1: .\" $OpenBSD: ssh-agent.1,v 1.65 2019/10/31 21:22:01 djm Exp $
1.7 markus 2: .\"
1.16 deraadt 3: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5: .\" All rights reserved
1.1 deraadt 6: .\"
1.16 deraadt 7: .\" As far as I am concerned, the code I have written for this software
8: .\" can be used freely for any purpose. Any derived versions of this
9: .\" software must be clearly marked as such, and if the derived work is
10: .\" incompatible with the protocol description in the RFC file, it must be
11: .\" called by a name other than "ssh" or "Secure Shell".
1.1 deraadt 12: .\"
1.22 deraadt 13: .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
14: .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
15: .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
1.8 deraadt 16: .\"
1.16 deraadt 17: .\" Redistribution and use in source and binary forms, with or without
18: .\" modification, are permitted provided that the following conditions
19: .\" are met:
20: .\" 1. Redistributions of source code must retain the above copyright
21: .\" notice, this list of conditions and the following disclaimer.
22: .\" 2. Redistributions in binary form must reproduce the above copyright
23: .\" notice, this list of conditions and the following disclaimer in the
24: .\" documentation and/or other materials provided with the distribution.
1.1 deraadt 25: .\"
1.16 deraadt 26: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.1 deraadt 36: .\"
1.66 jmc 37: .Dd $Mdocdate: October 31 2019 $
1.2 deraadt 38: .Dt SSH-AGENT 1
39: .Os
40: .Sh NAME
41: .Nm ssh-agent
42: .Nd authentication agent
43: .Sh SYNOPSIS
1.11 aaron 44: .Nm ssh-agent
1.52 jmc 45: .Op Fl c | s
1.67 ! jmc 46: .Op Fl \&Dd
1.32 markus 47: .Op Fl a Ar bind_address
1.57 djm 48: .Op Fl E Ar fingerprint_hash
1.65 djm 49: .Op Fl P Ar provider_whitelist
1.36 marc 50: .Op Fl t Ar life
1.46 sobrado 51: .Op Ar command Op Ar arg ...
1.67 ! jmc 52: .Nm ssh-agent
! 53: .Op Fl c | s
! 54: .Fl k
1.11 aaron 55: .Sh DESCRIPTION
1.2 deraadt 56: .Nm
1.14 markus 57: is a program to hold private keys used for public key authentication
1.56 sobrado 58: (RSA, DSA, ECDSA, Ed25519).
1.2 deraadt 59: .Nm
1.55 djm 60: is usually started in the beginning of an X-session or a login session, and
1.7 markus 61: all other windows or programs are started as clients to the ssh-agent
1.10 aaron 62: program.
63: Through use of environment variables the agent can be located
1.14 markus 64: and automatically used for authentication when logging in to other
1.1 deraadt 65: machines using
1.2 deraadt 66: .Xr ssh 1 .
67: .Pp
1.55 djm 68: The agent initially does not have any private keys.
69: Keys are added using
1.61 jcs 70: .Xr ssh 1
71: (see
72: .Cm AddKeysToAgent
73: in
74: .Xr ssh_config 5
75: for details)
76: or
1.55 djm 77: .Xr ssh-add 1 .
78: Multiple identities may be stored in
79: .Nm
80: concurrently and
81: .Xr ssh 1
82: will automatically use them if present.
83: .Xr ssh-add 1
84: is also used to remove keys from
85: .Nm
86: and to query the keys that are held in one.
87: .Pp
1.7 markus 88: The options are as follows:
89: .Bl -tag -width Ds
1.32 markus 90: .It Fl a Ar bind_address
1.48 sobrado 91: Bind the agent to the
1.49 sobrado 92: .Ux Ns -domain
93: socket
1.32 markus 94: .Ar bind_address .
95: The default is
1.53 djm 96: .Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
1.7 markus 97: .It Fl c
98: Generate C-shell commands on
99: .Dv stdout .
100: This is the default if
101: .Ev SHELL
102: looks like it's a csh style of shell.
1.58 djm 103: .It Fl D
104: Foreground mode.
105: When this option is specified
106: .Nm
107: will not fork.
1.46 sobrado 108: .It Fl d
109: Debug mode.
110: When this option is specified
111: .Nm
1.58 djm 112: will not fork and will write debug information to standard error.
1.57 djm 113: .It Fl E Ar fingerprint_hash
114: Specifies the hash algorithm used when displaying key fingerprints.
115: Valid options are:
116: .Dq md5
117: and
118: .Dq sha256 .
119: The default is
120: .Dq sha256 .
1.46 sobrado 121: .It Fl k
122: Kill the current agent (given by the
123: .Ev SSH_AGENT_PID
124: environment variable).
1.65 djm 125: .It Fl P Ar provider_whitelist
126: Specify a pattern-list of acceptable paths for PKCS#11 and security key shared
127: libraries that may be used with the
1.63 djm 128: .Fl s
1.65 djm 129: or
130: .Fl S
131: options to
1.63 djm 132: .Xr ssh-add 1 .
1.65 djm 133: The default is to allow loading libraries from
1.63 djm 134: .Dq /usr/lib/*,/usr/local/lib/* .
1.65 djm 135: Libraries that do not match the whitelist will be refused.
1.63 djm 136: See PATTERNS in
137: .Xr ssh_config 5
138: for a description of pattern-list syntax.
1.7 markus 139: .It Fl s
140: Generate Bourne shell commands on
141: .Dv stdout .
142: This is the default if
143: .Ev SHELL
144: does not look like it's a csh style of shell.
1.36 marc 145: .It Fl t Ar life
1.37 jmc 146: Set a default value for the maximum lifetime of identities added to the agent.
1.36 marc 147: The lifetime may be specified in seconds or in a time format specified in
1.43 dtucker 148: .Xr sshd_config 5 .
1.36 marc 149: A lifetime specified for an identity with
150: .Xr ssh-add 1
151: overrides this value.
152: Without this option the default maximum lifetime is forever.
1.7 markus 153: .El
154: .Pp
1.60 jmc 155: If a command line is given, this is executed as a subprocess of the agent.
1.7 markus 156: When the command dies, so does the agent.
157: .Pp
1.1 deraadt 158: The idea is that the agent is run in the user's local PC, laptop, or
1.10 aaron 159: terminal.
160: Authentication data need not be stored on any other
1.1 deraadt 161: machine, and authentication passphrases never go over the network.
1.2 deraadt 162: However, the connection to the agent is forwarded over SSH
1.1 deraadt 163: remote logins, and the user can thus use the privileges given by the
164: identities anywhere in the network in a secure way.
1.2 deraadt 165: .Pp
1.38 jmc 166: There are two main ways to get an agent set up:
1.40 dtucker 167: The first is that the agent starts a new subcommand into which some environment
168: variables are exported, eg
169: .Cm ssh-agent xterm & .
170: The second is that the agent prints the needed shell commands (either
1.7 markus 171: .Xr sh 1
172: or
173: .Xr csh 1
1.47 sobrado 174: syntax can be generated) which can be evaluated in the calling shell, eg
1.40 dtucker 175: .Cm eval `ssh-agent -s`
176: for Bourne-type shells such as
177: .Xr sh 1
178: or
179: .Xr ksh 1
180: and
1.41 deraadt 181: .Cm eval `ssh-agent -c`
1.40 dtucker 182: for
183: .Xr csh 1
184: and derivatives.
185: .Pp
1.7 markus 186: Later
187: .Xr ssh 1
1.23 deraadt 188: looks at these variables and uses them to establish a connection to the agent.
1.29 stevesk 189: .Pp
190: The agent will never send a private key over its request channel.
191: Instead, operations that require a private key will be performed
192: by the agent, and the result will be returned to the requester.
193: This way, private keys are not exposed to clients using the agent.
1.7 markus 194: .Pp
1.48 sobrado 195: A
1.49 sobrado 196: .Ux Ns -domain
197: socket is created and the name of this socket is stored in the
1.5 markus 198: .Ev SSH_AUTH_SOCK
1.1 deraadt 199: environment
1.10 aaron 200: variable.
201: The socket is made accessible only to the current user.
1.1 deraadt 202: This method is easily abused by root or another instance of the same
1.4 markus 203: user.
1.7 markus 204: .Pp
205: The
206: .Ev SSH_AGENT_PID
1.34 stevesk 207: environment variable holds the agent's process ID.
1.2 deraadt 208: .Pp
1.1 deraadt 209: The agent exits automatically when the command given on the command
210: line terminates.
1.2 deraadt 211: .Sh FILES
212: .Bl -tag -width Ds
1.64 jmc 213: .It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
1.49 sobrado 214: .Ux Ns -domain
215: sockets used to contain the connection to the authentication agent.
1.10 aaron 216: These sockets should only be readable by the owner.
217: The sockets should get automatically removed when the agent exits.
1.13 aaron 218: .El
1.39 jmc 219: .Sh SEE ALSO
220: .Xr ssh 1 ,
221: .Xr ssh-add 1 ,
222: .Xr ssh-keygen 1 ,
223: .Xr sshd 8
1.17 aaron 224: .Sh AUTHORS
1.64 jmc 225: .An -nosplit
226: OpenSSH is a derivative of the original and free ssh 1.2.12 release by
227: .An Tatu Ylonen .
228: .An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt
229: and
230: .An Dug Song
231: removed many bugs, re-added newer features and created OpenSSH.
232: .An Markus Friedl
233: contributed the support for SSH protocol versions 1.5 and 2.0.
![[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