PrivX SSH Agent
===============

The PrivX SSH Agent communicates with the PrivX CA to request
certificates and SSH keys for the SSH client.


Quick Start
-----------

To run PrivX SSH Agent on a single shell, use the command:

    # privx-agent-unix bash

This command starts the SSH agent and executes a bash shell. Next a PrivX server
needs to be added to the list of trusted servers:

    # privx-agent-ctl server probe https://172.18.0.1
    1 rawCerts, 0 verifiedChains
    PrivX server 'https://172.18.0.1' certificate is untrusted
    Server TLS certificate:
      Issuer        OU=PrivX TLS CA, CN=privx.local
      Subject       OU=PrivX Web Server, CN=privx.local
      Serial        1526990690
      Not Before    2018-05-22 12:04:50 +0000 UTC
      Not After     2020-05-21 12:04:50 +0000 UTC
      Fingerprints
        SHA1        AE 8D 4C 65 7B 72 A5 C2 11 84 19 CF 00 E4 5C A8 D8 C3 7C F4
        SHA256      D8 65 8F 07 9B F9 68 25 3D 4A C8 6D 1C A4 EB DE A9 5A FF F2 52 D7 0D 5D B8 3D E0 9E C1 22 FF 99

    Would you like to add this server to trusted servers? Y/N: Y

Next the PrivX user needs to login to PrivX CA using privx-agent-ctl:

    # privx-agent-ctl login username
    Password:

After login the PrivX SSH Agent is ready for serving SSH clients executed in the
SSH Agent's bash shell.

You can check PrivX SSH agent status using privx-agent-ctl:

    # privx-agent-ctl status
    PrivX SSH Agent Status
      PrivX Server          https://172.18.0.1
      Login status          username logged in


Starting PrivX SSH Agent Automatically
--------------------------------------

Bash users can place the following snippet in their .profile to start PrivX SSH Agent
automatically when logging in:

  # Start PrivX Agent unless there is already an ssh-agent running
  START_PRIVX_AGENT="yes"
  PRIVX_AGENT_UNIX="/usr/local/bin/privx-agent-unix"
  if [ -n "$START_PRIVX_AGENT" ] && [ -z "$SSH_AUTH_SOCK" ] && [ -x "$PRIVX_AGENT_UNIX" ]; then
      PRIVX_AGENT_DIR=`mktemp -d /tmp/ssh-XXXXXXXXXX 2>/dev/null || mktemp -d -t 'mytmpdir'`
      export PRIVX_AUTH_SOCK="$PRIVX_AGENT_DIR/agent.$$"
      export PRIVX_AGENT_PROXY="$PRIVX_AGENT_DIR/proxy.$$"
      setsid nohup $PRIVX_AGENT_UNIX -a $PRIVX_AUTH_SOCK -x $PRIVX_AGENT_PROXY -config $HOME/.privx/agent.json > /dev/null 2>&1 &
      export PRIVX_AGENT_PID=$!
      export SSH_AUTH_SOCK="$PRIVX_AUTH_SOCK"
      export SSH_AGENT_PID="$PRIVX_AGENT_PID"
      trap 'test -n "$SSH_AGENT_PID" && kill $SSH_AGENT_PID' 0
  fi

On some distributions the native ssh-agent starts after PrivX SSH Agent and the environment
variables get overwritten. The PrivX Agent environment variables can be restored with the
following command:

    # eval `privx-agent-ctl setenv`


Amazon Webservices Role Grants
------------------------------

PrivX Agent can be used to request temporary AWS access tokens from the PrivX server.

Refer to PrivX admin manual for instructions on how to enable and configure this feature on the
PrivX server and your AWS account.


Usage
-----

PrivX SSH Agent usage:

    Usage of privx-agent-unix:
      -a string
            Bind address for the agent UNIX-domain socket.
      -aws-credentials-file string
            Path to AWS API credentials file (default "~/.aws/credentials")
      -c    Generate C-shell commands to stdout.
      -config string
            PrivX agent configuration file (default "$HOME/.privx/agent.json")
      -d    Debug mode.
      -privx string
            PrivX CA base URL
      -s    Generate Bourne shell commands on stdout.
      -tls-cert string
            PrivX TLS CA Certificate
      -tls-cert-data string
            PrivX TLS CA Certificate data in Base64 encoded format
      -v    Output version information and exit
      -x string
            Bind address for the agent proxy UNIX-domain socket.


PrivX Agent Ctl usage:

    usage: privx-agent-ctl [OPTION]... command [ARGS]
    Possible commands are:
      status                Display PrivX SSH Agent login status
      login [USERNAME]      Login to PrivX SSH Agent
      logout                Logout
      target list           List accessible SSH targets
      target set TARGET     Set target
      target unset          Unset target
      role list             List available roles
      role set ROLE         Set role
      role unset            Unset role
      aws-role list         List available AWS roles
      aws-role set ROLE     Set AWS role
      aws-role unset        Unset AWS role
      server list           List trusted PrivX servers
      server probe URL      Probe PrivX server at URL
      server set URL        Select PrivX server at URL
      server remove URL     Remove PrivX server at URL
      setenv                Output env variables
      ssh [OPTS] TARGET     Open ssh connection to target
      sftp [OPTS] TARGET[:FILE] [FILE]
                              Open sftp connection to target
      scp [OPTS] TARGET[:FILE] [FILE]
                              Open scp connection to target
    Possible options are:
      -c    Output env variables in C-shell format
      -s    Output env variables in Bourne shell format
      -v    Output version information and exit


PrivX nc usage:

    usage: privx-nc [-x proxyaddr] host port



Copyright 2019 SSH Communications Security Corp.

