PROXY-AGENT(7)                                                  PROXY-AGENT(7)



NAME
       proxy-agent  -  jacket to proxy ssh-agent connections from an escalated
       processes

SYNOPSIS
       proxy-agent -P pid [-C config] [-f file] [-g group] [-R root] [-u user]
       mnemonic program euid:egid cred_type:cred
       proxy-agent -h|-H
       proxy-agent -V

DESCRIPTION
       Ssh-agent(1),  the  ssh(1) cache for cryptographic keys, restricts ser-
       vice-access to processes with its same effect uid.   It  may  use  get-
       peereid(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.

       When  an  escalated process needs access to the agent cache proxy-agent
       proxies the request through to the original agent by  dropping  uid  to
       the original.  Thus defeating the internal check completely.

       This makes it possible to leverage the agent cache in a few ways:

       Add a key the client cannot normally access
              Using  the  -t life option, and escalated permissions, one might
              install a key in the original agent that could not otherwise  be
              read by the Customer.

       Use an existing key to access a remote ssh service
              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.

       Allow port forwarding that only the superuser can initiate
              Forwarding  a  local  privileged port requires superuser access,
              but we need the Customer's credentials to  gain  access  to  the
              remote server.

       These  use-cases  for  ssh-agent are forbidden by the service, but that
       never stopped us before, did it?

       The jacket is intended to allow op(1) escalation rules to proxy connec-
       tions  back  to  the  client's  agent.  The escalation will not exit(3)
       until all the proxy connections have finished.  This allows  for  back-
       ground tasks to finish.

OPTIONS
       This  program  takes  all the op provided options, but must be run as a
       jacket (not a helmet) to keep the co-process proxy running for the life
       of  the  escalated process.  Only the euid:egid parameters are actually
       relevant, but op provides the complete set to every jacket, so we  san-
       ity check them, just the same.

ENVIRONMENT
       These  are  almost  always  forced in the op stanza for each escalation
       rule:

       $SSH_AUTH_SOCK
              The default environment variable to read and replace.

       $SPROXY_FROM
              The name of a different environment  variable  to  proxy.   Note
              that  the  proxy  doesn't  know  anything  about  the  ssh-agent
              protocol.

       $SPROXY_ENV
              If you need to change the  name  of  the  proxy  variable,  this
              causes  the proxy socket name to be deposited in the named vari-
              able.

       $SPROXY_TO
              This is a mktemp(3) template that describes where to  place  the
              visible  end-point of the domain socket.  More than a single set
              of "XXXXXX" may be included in the template, all will be  filled
              in  by  either  mkdtemp(3) or mktemp(3). The default  is visible
              under  -V  ("/tmp/sPad-XXXXXX/agent-XXXXXX").   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.

       $SPROXY_REVEAL
              The standard reveal logic, see op-jacket(7).

EXAMPLES
       These are example from the command-line:

       /usr/local/libexec/jacket/proxy-agent -V
              Output only the version of the program  and  the  default  proxy
              template, then exit.

       /usr/local/libexec/jacket/proxy-agent -H
              Output only a summary of the environment expected.

       All  of these are snips from the op access.cf file.  Note that you must
       allow the environment variable which contains the original agent socket
       path into the escalated environment.

       jacket=/usr/local/libexec/jacket/proxy-agent $SSH_AUTH_SOCK
              This  is  the most common spelling, just proxy the in-scope ssh-
              agent socket through to the escalated process.

       $SSH_AUTH_SOCK $SPROXY_ENV=HIS_AGENT
       jacket=/usr/local/libexec/jacket/proxy-agent
              Deposit the path  to  the  proxy  in  the  environment  variable
              $HIS_AGENT.   The  original  variable is expunged from the esca-
              lated environment.

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

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

SEE ALSO
       op(1l), op-jacket(7), getpeereid(3), ssh-agent(1), ssh(1)



                                     LOCAL                      PROXY-AGENT(7)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | EXAMPLES | BUGS | AUTHOR | SEE ALSO