summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorjmc@openbsd.org <jmc@openbsd.org>2019-11-28 12:23:25 +0000
committerDamien Miller <djm@mindrot.org>2019-11-29 11:17:39 +1100
commit9a0e01bd0c61f553ead96b5af84abd73865847b8 (patch)
treefd8f059fc83c4d23ab6a6b25f0a386146ee8c9ff
parent5ca52c0f2e5e7f7d01d8d557b994b5c2087bed00 (diff)
upstream: reshuffle the text to read better; input from naddy,
djmc, and dtucker OpenBSD-Commit-ID: a0b2aca2b67614dda3d6618ea097bf0610c35013
-rw-r--r--ssh-agent.1158
1 files changed, 76 insertions, 82 deletions
diff --git a/ssh-agent.1 b/ssh-agent.1
index 9129d36ff..2a1268af7 100644
--- a/ssh-agent.1
+++ b/ssh-agent.1
@@ -1,4 +1,4 @@
1.\" $OpenBSD: ssh-agent.1,v 1.67 2019/11/19 16:02:32 jmc Exp $ 1.\" $OpenBSD: ssh-agent.1,v 1.68 2019/11/28 12:23:25 jmc Exp $
2.\" 2.\"
3.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 3.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
@@ -34,7 +34,7 @@
34.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 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. 35.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36.\" 36.\"
37.Dd $Mdocdate: November 19 2019 $ 37.Dd $Mdocdate: November 28 2019 $
38.Dt SSH-AGENT 1 38.Dt SSH-AGENT 1
39.Os 39.Os
40.Sh NAME 40.Sh NAME
@@ -54,37 +54,12 @@
54.Fl k 54.Fl k
55.Sh DESCRIPTION 55.Sh DESCRIPTION
56.Nm 56.Nm
57is a program to hold private keys used for public key authentication 57is a program to hold private keys used for public key authentication.
58(RSA, DSA, ECDSA, Ed25519).
59.Nm
60is usually started in the beginning of an X-session or a login session, and
61all other windows or programs are started as clients to the ssh-agent
62program.
63Through use of environment variables the agent can be located 58Through use of environment variables the agent can be located
64and automatically used for authentication when logging in to other 59and automatically used for authentication when logging in to other
65machines using 60machines using
66.Xr ssh 1 . 61.Xr ssh 1 .
67.Pp 62.Pp
68The agent initially does not have any private keys.
69Keys are added using
70.Xr ssh 1
71(see
72.Cm AddKeysToAgent
73in
74.Xr ssh_config 5
75for details)
76or
77.Xr ssh-add 1 .
78Multiple identities may be stored in
79.Nm
80concurrently and
81.Xr ssh 1
82will automatically use them if present.
83.Xr ssh-add 1
84is also used to remove keys from
85.Nm
86and to query the keys that are held in one.
87.Pp
88The options are as follows: 63The options are as follows:
89.Bl -tag -width Ds 64.Bl -tag -width Ds
90.It Fl a Ar bind_address 65.It Fl a Ar bind_address
@@ -125,17 +100,17 @@ environment variable).
125.It Fl P Ar provider_whitelist 100.It Fl P Ar provider_whitelist
126Specify a pattern-list of acceptable paths for PKCS#11 and security key shared 101Specify a pattern-list of acceptable paths for PKCS#11 and security key shared
127libraries that may be used with the 102libraries that may be used with the
128.Fl s
129or
130.Fl S 103.Fl S
104or
105.Fl s
131options to 106options to
132.Xr ssh-add 1 . 107.Xr ssh-add 1 .
133The default is to allow loading libraries from
134.Dq /usr/lib/*,/usr/local/lib/* .
135Libraries that do not match the whitelist will be refused. 108Libraries that do not match the whitelist will be refused.
136See PATTERNS in 109See PATTERNS in
137.Xr ssh_config 5 110.Xr ssh_config 5
138for a description of pattern-list syntax. 111for a description of pattern-list syntax.
112The default whitelist is
113.Dq /usr/lib/*,/usr/local/lib/* .
139.It Fl s 114.It Fl s
140Generate Bourne shell commands on 115Generate Bourne shell commands on
141.Dv stdout . 116.Dv stdout .
@@ -150,64 +125,82 @@ A lifetime specified for an identity with
150.Xr ssh-add 1 125.Xr ssh-add 1
151overrides this value. 126overrides this value.
152Without this option the default maximum lifetime is forever. 127Without this option the default maximum lifetime is forever.
128.It Ar command Op Ar arg ...
129If a command (and optional arguments) is given,
130this is executed as a subprocess of the agent.
131The agent exits automatically when the command given on the command
132line terminates.
153.El 133.El
154.Pp 134.Pp
155If a command line is given, this is executed as a subprocess of the agent. 135There are two main ways to get an agent set up.
156When the command dies, so does the agent. 136The first is at the start of an X session,
157.Pp 137where all other windows or programs are started as children of the
158The idea is that the agent is run in the user's local PC, laptop, or 138.Nm
159terminal. 139program.
160Authentication data need not be stored on any other 140The agent starts a command under which its environment
161machine, and authentication passphrases never go over the network. 141variables are exported, for example
162However, the connection to the agent is forwarded over SSH
163remote logins, and the user can thus use the privileges given by the
164identities anywhere in the network in a secure way.
165.Pp
166There are two main ways to get an agent set up:
167The first is that the agent starts a new subcommand into which some environment
168variables are exported, eg
169.Cm ssh-agent xterm & . 142.Cm ssh-agent xterm & .
170The second is that the agent prints the needed shell commands (either 143When the command terminates, so does the agent.
171.Xr sh 1
172or
173.Xr csh 1
174syntax can be generated) which can be evaluated in the calling shell, eg
175.Cm eval `ssh-agent -s`
176for Bourne-type shells such as
177.Xr sh 1
178or
179.Xr ksh 1
180and
181.Cm eval `ssh-agent -c`
182for
183.Xr csh 1
184and derivatives.
185.Pp 144.Pp
186Later 145The second method is used for a login session.
146When
147.Nm
148is started,
149it prints the shell commands required to set its environment variables,
150which in turn can be evaluated in the calling shell, for example
151.Cm eval `ssh-agent -s` .
152.Pp
153In both cases,
187.Xr ssh 1 154.Xr ssh 1
188looks at these variables and uses them to establish a connection to the agent. 155looks at these environment variables and uses them to establish a connection to the agent.
189.Pp 156.Pp
190The agent will never send a private key over its request channel. 157The agent initially does not have any private keys.
191Instead, operations that require a private key will be performed 158Keys are added using
192by the agent, and the result will be returned to the requester. 159.Xr ssh-add 1
193This way, private keys are not exposed to clients using the agent. 160or by
161.Xr ssh 1
162when
163.Cm AddKeysToAgent
164is set in
165.Xr ssh_config 5 .
166Multiple identities may be stored in
167.Nm
168concurrently and
169.Xr ssh 1
170will automatically use them if present.
171.Xr ssh-add 1
172is also used to remove keys from
173.Nm
174and to query the keys that are held in one.
194.Pp 175.Pp
195A 176Connections to
177.Nm
178may be forwarded from further remote hosts using the
179.Fl A
180option to
181.Xr ssh 1
182(but see the caveats documented therein),
183avoiding the need for authentication data to be stored on other machines.
184Authentication passphrases and private keys never go over the network:
185the connection to the agent is forwarded over SSH remote connections
186and the result is returned to the requester,
187allowing the user access to their identities anywhere in the network
188in a secure fashion.
189.Sh ENVIRONMENT
190.Bl -tag -width "SSH_AGENT_PID"
191.It Ev SSH_AGENT_PID
192When
193.Nm
194starts, it stores the name of the agent's process ID (PID) in this variable.
195.It Ev SSH_AUTH_SOCK
196When
197.Nm
198starts, it creates a
196.Ux Ns -domain 199.Ux Ns -domain
197socket is created and the name of this socket is stored in the 200socket and stores its pathname in this variable.
198.Ev SSH_AUTH_SOCK 201It is accessible only to the current user,
199environment 202but is easily abused by root or another instance of the same user.
200variable. 203.El
201The socket is made accessible only to the current user.
202This method is easily abused by root or another instance of the same
203user.
204.Pp
205The
206.Ev SSH_AGENT_PID
207environment variable holds the agent's process ID.
208.Pp
209The agent exits automatically when the command given on the command
210line terminates.
211.Sh FILES 204.Sh FILES
212.Bl -tag -width Ds 205.Bl -tag -width Ds
213.It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid> 206.It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
@@ -220,6 +213,7 @@ The sockets should get automatically removed when the agent exits.
220.Xr ssh 1 , 213.Xr ssh 1 ,
221.Xr ssh-add 1 , 214.Xr ssh-add 1 ,
222.Xr ssh-keygen 1 , 215.Xr ssh-keygen 1 ,
216.Xr ssh_config 5 ,
223.Xr sshd 8 217.Xr sshd 8
224.Sh AUTHORS 218.Sh AUTHORS
225.An -nosplit 219.An -nosplit