upstream: reshuffle the text to read better; input from naddy,

djmc, and dtucker

OpenBSD-Commit-ID: a0b2aca2b67614dda3d6618ea097bf0610c35013

ssh-agent.1

@@ -1,4 +1,4 @@
-.\" $OpenBSD: ssh-agent.1,v 1.67 2019/11/19 16:02:32 jmc Exp $
+.\" $OpenBSD: ssh-agent.1,v 1.68 2019/11/28 12:23:25 jmc Exp $
 .\"
 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
@@ -34,7 +34,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 19 2019 $
+.Dd $Mdocdate: November 28 2019 $
 .Dt SSH-AGENT 1
 .Os
 .Sh NAME
@@ -54,37 +54,12 @@
 .Fl k
 .Sh DESCRIPTION
 .Nm
-is a program to hold private keys used for public key authentication
+is a program to hold private keys used for public key authentication.
-(RSA, DSA, ECDSA, Ed25519).
-.Nm
-is usually started in the beginning of an X-session or a login session, and
-all other windows or programs are started as clients to the ssh-agent
-program.
 Through use of environment variables the agent can be located
 and automatically used for authentication when logging in to other
 machines using
 .Xr ssh 1 .
 .Pp
-The agent initially does not have any private keys.
-Keys are added using
-.Xr ssh 1
-(see
-.Cm AddKeysToAgent
-in
-.Xr ssh_config 5
-for details)
-or
-.Xr ssh-add 1 .
-Multiple identities may be stored in
-.Nm
-concurrently and
-.Xr ssh 1
-will automatically use them if present.
-.Xr ssh-add 1
-is also used to remove keys from
-.Nm
-and to query the keys that are held in one.
-.Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl a Ar bind_address
@@ -125,17 +100,17 @@ environment variable).
 .It Fl P Ar provider_whitelist
 Specify a pattern-list of acceptable paths for PKCS#11 and security key shared
 libraries that may be used with the
-.Fl s
-or
 .Fl S
+or
+.Fl s
 options to
 .Xr ssh-add 1 .
-The default is to allow loading libraries from
-.Dq /usr/lib/*,/usr/local/lib/* .
 Libraries that do not match the whitelist will be refused.
 See PATTERNS in
 .Xr ssh_config 5
 for a description of pattern-list syntax.
+The default whitelist is
+.Dq /usr/lib/*,/usr/local/lib/* .
 .It Fl s
 Generate Bourne shell commands on
 .Dv stdout .
@@ -150,64 +125,82 @@ A lifetime specified for an identity with
 .Xr ssh-add 1
 overrides this value.
 Without this option the default maximum lifetime is forever.
-.El
+.It Ar command Op Ar arg ...
-.Pp
+If a command (and optional arguments) is given,
-If a command line is given, this is executed as a subprocess of the agent.
+this is executed as a subprocess of the agent.
-When the command dies, so does the agent.
-.Pp
-The idea is that the agent is run in the user's local PC, laptop, or
-terminal.
-Authentication data need not be stored on any other
-machine, and authentication passphrases never go over the network.
-However, the connection to the agent is forwarded over SSH
-remote logins, and the user can thus use the privileges given by the
-identities anywhere in the network in a secure way.
-.Pp
-There are two main ways to get an agent set up:
-The first is that the agent starts a new subcommand into which some environment
-variables are exported, eg
-.Cm ssh-agent xterm & .
-The second is that the agent prints the needed shell commands (either
-.Xr sh 1
-or
-.Xr csh 1
-syntax can be generated) which can be evaluated in the calling shell, eg
-.Cm eval `ssh-agent -s`
-for Bourne-type shells such as
-.Xr sh 1
-or
-.Xr ksh 1
-and
-.Cm eval `ssh-agent -c`
-for
-.Xr csh 1
-and derivatives.
-.Pp
-Later
-.Xr ssh 1
-looks at these variables and uses them to establish a connection to the agent.
-.Pp
-The agent will never send a private key over its request channel.
-Instead, operations that require a private key will be performed
-by the agent, and the result will be returned to the requester.
-This way, private keys are not exposed to clients using the agent.
-.Pp
-A
-.Ux Ns -domain
-socket is created and the name of this socket is stored in the
-.Ev SSH_AUTH_SOCK
-environment
-variable.
-The socket is made accessible only to the current user.
-This method is easily abused by root or another instance of the same
-user.
-.Pp
-The
-.Ev SSH_AGENT_PID
-environment variable holds the agent's process ID.
-.Pp
 The agent exits automatically when the command given on the command
 line terminates.
+.El
+.Pp
+There are two main ways to get an agent set up.
+The first is at the start of an X session,
+where all other windows or programs are started as children of the
+.Nm
+program.
+The agent starts a command under which its environment
+variables are exported, for example
+.Cm ssh-agent xterm & .
+When the command terminates, so does the agent.
+.Pp
+The second method is used for a login session.
+When
+.Nm
+is started,
+it prints the shell commands required to set its environment variables,
+which in turn can be evaluated in the calling shell, for example
+.Cm eval `ssh-agent -s` .
+.Pp
+In both cases,
+.Xr ssh 1
+looks at these environment variables and uses them to establish a connection to the agent.
+.Pp
+The agent initially does not have any private keys.
+Keys are added using
+.Xr ssh-add 1
+or by
+.Xr ssh 1
+when
+.Cm AddKeysToAgent
+is set in
+.Xr ssh_config 5 .
+Multiple identities may be stored in
+.Nm
+concurrently and
+.Xr ssh 1
+will automatically use them if present.
+.Xr ssh-add 1
+is also used to remove keys from
+.Nm
+and to query the keys that are held in one.
+.Pp
+Connections to
+.Nm
+may be forwarded from further remote hosts using the
+.Fl A
+option to
+.Xr ssh 1
+(but see the caveats documented therein),
+avoiding the need for authentication data to be stored on other machines.
+Authentication passphrases and private keys never go over the network:
+the connection to the agent is forwarded over SSH remote connections
+and the result is returned to the requester,
+allowing the user access to their identities anywhere in the network
+in a secure fashion.
+.Sh ENVIRONMENT
+.Bl -tag -width "SSH_AGENT_PID"
+.It Ev SSH_AGENT_PID
+When
+.Nm
+starts, it stores the name of the agent's process ID (PID) in this variable.
+.It Ev SSH_AUTH_SOCK
+When
+.Nm
+starts, it creates a
+.Ux Ns -domain
+socket and stores its pathname in this variable.
+It is accessible only to the current user,
+but is easily abused by root or another instance of the same user.
+.El
 .Sh FILES
 .Bl -tag -width Ds
 .It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
@@ -220,6 +213,7 @@ The sockets should get automatically removed when the agent exits.
 .Xr ssh 1 ,
 .Xr ssh-add 1 ,
 .Xr ssh-keygen 1 ,
+.Xr ssh_config 5 ,
 .Xr sshd 8
 .Sh AUTHORS
 .An -nosplit