.\" $Id: proxy-agent.man,v 1.4 2012/02/24 15:07:27 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man7/proxy-agent.7
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/proxy-agent.7*
.TH PROXY-AGENT 7 LOCAL
.SH NAME
proxy-agent - jacket to proxy ssh-agent connections from an escalated processes

.SH SYNOPSIS
.ds PN "proxy-agent
\fI\*(PN\fP \fB\-P\fP\~\fIpid\fP [\fB\-C\fP\~config] [\fB\-f\fP\~\fIfile\fP] [\fB\-g\fP\~\fIgroup\fP] [\fB\-R\fP\~\fIroot\fP] [\fB\-u\fP\~\fIuser\fP] \fImnemonic\fP \fIprogram\fP \fIeuid\fP:\fIegid\fP \fIcred_type\fP:\fIcred\fP
.br
\fI\*(PN\fP \fB\-h\fP|\fB\-H\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION

\fBSsh-agent\fP(1), the \fBssh\fP(1) cache for cryptographic keys,
restricts service-access to processes with its same effect uid.
It may use \fBgetpeereid\fP(3) to do this (depending on the platform).
This restriction is totally unnecessary as file permissions already
protect the directory and the socket's visible end-point.

.P
When an escalated process needs access to the agent cache \fI\*(PN\fP
proxies the request through to the original agent by dropping uid to
the original.  Thus defeating the internal check completely.

.P
This makes it possible to leverage the agent cache in a few ways:
.TP
.nf
Add a key the client cannot normally access
.fi
Using the \fB\-t\fP \fIlife\fP option, and escalated permissions, one
might install a key in the original agent that could not otherwise
be read by the Customer.
.TP
.nf
Use an existing key to access a remote \fBssh\fP service
.fi
For example deposit data streams (backup, log files, reports) to a
remote host over a secure connection using the credentials of
the Customer, but the access of the escalated login.
.TP
.nf
Allow port forwarding that only the superuser can initiate
.fi
Forwarding a local privileged port requires superuser access, but we
need the Customer's credentials to gain access to the remote server.
.PP
These use-cases for \fBssh-agent\fP are forbidden by the service,
but that never stopped us before, did it?
.PP
The jacket is intended to allow \fBop\fP(1) escalation rules to
proxy connections back to the client's agent.  The escalation will
not \fBexit\fP(3) until all the proxy connections have finished.
This allows for background tasks to finish.

.SH OPTIONS
This program takes all the \fBop\fP provided options, but \fBmust\fP
be run as a jacket (not a helmet) to keep the co-process proxy running
for the life of the escalated process.  Only the \fIeuid\fP:\fIegid\fP
parameters are actually relevant, but \fBop\fP provides the complete
set to every jacket, so we sanity check them, just the same.

.SH ENVIRONMENT
.TP
.nf
\fBSSH_AUTH_SOCK\fP
.fi
The default environment variable to read and replace.
.TP
.nf
\fBSPROXY_FROM\fP
.fi
The name of a different environment variable to proxy.  Note that
the proxy doesn't know anything about the \fBssh-agent\fP protocol.
.TP
.nf
\fBSPROXY_ENV\fP
.fi
If you need to change the name of the proxy variable, this causes
the proxy socket name to be deposited in the named variable.
.TP
.nf
\fBSPROXY_TO\fP
.fi
This is a \fBmktemp\fP(3) template that describes where to place the
visible end-point of the domain socket.  More than a single set of
\*(lqXXXXXX\*(rq may be included in the template, all will be
filled in by either \fBmkdtemp\fP or \fBmktemp\fP. The default  is
visible under \fB\-V\fP (\*(lq/tmp/sPad-XXXXXX/agent-XXXXXX\*(rq).
Plain directory names are allowed as well, for reasons that are
only clear under a local site policy that you don't want to understand.
.TP
.nf
\fBSPROXY_REVEAL\fP
.fi
The standard reveal logic, see \fBop-jacket\fP(7).

.SH EXAMPLES
These are example from the command-line:
.TP
.nf
/usr/local/libexec/jacket/proxy-agent \-V
.fi
Output the version and the default proxy template.
.TP
.nf
/usr/local/libexec/jacket/proxy-agent \-H
.fi
Output a summary of the environment expected.

.P
All of these are snips from the \fBop\fP \fIaccess.cf\fP file.
Note that you \fBmust\fP allow the environment variable which
contains the original agent socket path into the escalated
environment.
.PD 0
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/proxy-agent $SSH_AUTH_SOCK
.fi
This is the most common spelling, just proxy the in-scope \fBssh-agent\fP
socket through to the escalated process.
.sp
.TP
.nf
$SSH_AUTH_SOCK $SPROXY_ENV=HIS_AGENT
.fi
.TP
.nf
jacket=/usr/local/libexec/jacket/proxy-agent
.fi
Deposit the path to the proxy in the environment variable $HIS_AGENT.
The original variable is expunged from the escalated environment.
.PD

.SH BUGS
.P
Job control is flaky in the current implementation. Do not suspend
the escalated program.

.SH AUTHOR
K S Braunsdorf, from the Non-Player Character Guild
.br
op at-not-a-spammer ksb dot npcguild.org

.SH "SEE ALSO"
.hlm 0
op(1l), op-jacket(7), getpeereid(3), ssh-agent(1), ssh(1)