172 lines
4.8 KiB
Groff
172 lines
4.8 KiB
Groff
.\" $OpenBSD: ssh-agent.1,v 1.8 1999/11/16 23:59:21 deraadt Exp $
|
|
.\"
|
|
.\" -*- nroff -*-
|
|
.\"
|
|
.\" ssh-agent.1
|
|
.\"
|
|
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
|
|
.\"
|
|
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
|
|
.\" All rights reserved
|
|
.\"
|
|
.\" Created: Sat Apr 23 20:10:43 1995 ylo
|
|
.\"
|
|
.Dd September 25, 1999
|
|
.Dt SSH-AGENT 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ssh-agent
|
|
.Nd authentication agent
|
|
.Sh SYNOPSIS
|
|
.Nm ssh-agent
|
|
.Op Fl c Li | Fl s
|
|
.Op Fl k
|
|
.Oo
|
|
.Ar command
|
|
.Op Ar args ...
|
|
.Oc
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a program to hold authentication private keys. The
|
|
idea is that
|
|
.Nm
|
|
is 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 RSA authentication when logging in to other
|
|
machines using
|
|
.Xr ssh 1 .
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl c
|
|
Generate C-shell commands on
|
|
.Dv stdout .
|
|
This is the default if
|
|
.Ev SHELL
|
|
looks like it's a csh style of shell.
|
|
.It Fl s
|
|
Generate Bourne shell commands on
|
|
.Dv stdout .
|
|
This is the default if
|
|
.Ev SHELL
|
|
does not look like it's a csh style of shell.
|
|
.It Fl k
|
|
Kill the current agent (given by the
|
|
.Ev SSH_AGENT_PID
|
|
environment variable).
|
|
.El
|
|
.Pp
|
|
If a commandline is given, this is executed as a subprocess of the agent.
|
|
When the command dies, so does the agent.
|
|
.Pp
|
|
The agent initially does not have any private keys. Keys are added
|
|
using
|
|
.Xr ssh-add 1 .
|
|
When executed without arguments,
|
|
.Xr ssh-add 1
|
|
adds the
|
|
.Pa $HOME/.ssh/identity
|
|
file. If the identity has a passphrase,
|
|
.Xr ssh-add 1
|
|
asks for the passphrase (using a small X11 application if running
|
|
under X11, or from the terminal if running without X). It then sends
|
|
the identity to the agent. Several identities can be stored in the
|
|
agent; the agent can automatically use any of these identities.
|
|
.Ic ssh-add -l
|
|
displays the identities currently held by 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 setup: Either you let the agent
|
|
start a new subcommand into which some environment variables are exported, or
|
|
you let the agent print the needed shell commands (either
|
|
.Xr sh 1
|
|
or
|
|
.Xr csh 1
|
|
syntax can be generated) which can be evalled in the calling shell.
|
|
Later
|
|
.Xr ssh 1
|
|
look at these variables and use them to establish a connection to the agent.
|
|
.Pp
|
|
A unix-domain socket is created
|
|
.Pq Pa /tmp/ssh-XXXXXXXX/agent.<pid> ,
|
|
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 PID.
|
|
.Pp
|
|
The agent exits automatically when the command given on the command
|
|
line terminates.
|
|
.Pp
|
|
Here's a trick that will allow you to start this up from your .bash_profile (just put it in as the first thing that happens):
|
|
.Sp
|
|
.Vb 1
|
|
|
|
\& [ ! "$SSH_AGENT_PID" ] && exec ssh-agent -- bash --login
|
|
\& ssh-add
|
|
.Ve
|
|
.Sh FILES
|
|
.Bl -tag -width Ds
|
|
.It Pa $HOME/.ssh/identity
|
|
Contains the RSA authentication identity of the user. This file
|
|
should not be readable by anyone but the user. It is possible to
|
|
specify a passphrase when generating the key; that passphrase will be
|
|
used to encrypt the private part of this file. This file
|
|
is not used by
|
|
.Nm
|
|
but is normally added to the agent using
|
|
.Xr ssh-add 1
|
|
at login time.
|
|
.It Pa /tmp/ssh-XXXX/agent.<pid> ,
|
|
Unix-domain sockets used to contain the connection to the
|
|
authentication agent. These sockets should only be readable by the
|
|
owner. The sockets should get automatically removed when the agent
|
|
exits.
|
|
.Sh AUTHOR
|
|
Tatu Ylonen <ylo@cs.hut.fi>
|
|
.Pp
|
|
OpenSSH
|
|
is a derivative of the original (free) ssh 1.2.12 release, but with bugs
|
|
removed and newer features re-added. Rapidly after the 1.2.12 release,
|
|
newer versions bore successively more restrictive licenses. This version
|
|
of OpenSSH
|
|
.Bl -bullet
|
|
.It
|
|
has all components of a restrictive nature (ie. patents, see
|
|
.Xr ssl 8 )
|
|
directly removed from the source code; any licensed or patented components
|
|
are chosen from
|
|
external libraries.
|
|
.It
|
|
has been updated to support ssh protocol 1.5.
|
|
.It
|
|
contains added support for
|
|
.Xr kerberos 8
|
|
authentication and ticket passing.
|
|
.It
|
|
supports one-time password authentication with
|
|
.Xr skey 1 .
|
|
.El
|
|
.Pp
|
|
The libraries described in
|
|
.Xr ssl 8
|
|
are required for proper operation.
|
|
.Sh SEE ALSO
|
|
.Xr ssh 1 ,
|
|
.Xr ssh-add 1 ,
|
|
.Xr ssh-keygen 1 ,
|
|
.Xr sshd 8 ,
|
|
.Xr ssl 8
|