upstream: reshuffle the text to read better; input from naddy,
djmc, and dtucker OpenBSD-Commit-ID: a0b2aca2b67614dda3d6618ea097bf0610c35013
This commit is contained in:
jmc@openbsd.org
Damien Miller
parent
5ca52c0f2e
commit
9a0e01bd0c
170
ssh-agent.1
170
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
|
||||
(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.
|
||||
is a program to hold private keys used for public key authentication.
|
||||
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
|
||||
.Pp
|
||||
If a command line is given, 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
|
||||
.It Ar command Op Ar arg ...
|
||||
If a command (and optional arguments) is given,
|
||||
this is executed as a subprocess of the agent.
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue