SSH Agent support in PyHoca-GUI / Python X2Go
=============================================

Quotation from the ssh-agent man page:

"""
[...]

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.

A UNIX-domain socket is created and the name of this socket is stored
in the 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.

[...]
"""

So the benefit of SSH agent support is: no need to have private SSH keys
on remote systems anymore. You can keep your private ID files locally
and use SSH agent to handle authentication requests, even if you have
a chain of systems that you log in to:

  local-machine -> machine-1 -> machine-2 -> machine-3 ...

The requirement for SSH agent usage: the system administrators of the
remote hosts must be trustworthy. They cannot obtain your private keys,
but they can use the SSH agent socket and log into systems in your
login chain under your identity. So, BEWARE!!!


1. AUTHENTICATION AGAINST SSH AGENT
-----------------------------------

This feature has been added to Python X2Go 0.2.1.0.

PyHoca-GUI / Python X2Go is aware of local SSH agents and can authenticated
against those. Use this feature with the following session profile options
set:

  [x] Discover SSH keys or use SSH agent for X2Go authentication

  autologin = true (or 1)

  [x] Discover SSH keys or use SSH agent for proxy authentication

  sshproxyautologin = true (or 1)

Do not forget to run ssh-add (see the man page for more info).

2. AUTHENTICATION REQUEST FORWARDING TO YOUR LOCAL SSH AGENT
------------------------------------------------------------

This feature has been added to Python X2Go 0.2.1.0 and requires Python Paramiko
1.8.0.

PyHoca-GUI / Python X2Go supports forwarding of SSH agent authentication request.
Basically, you could say that the -A command line switch of the OpenSSH client
is now also available with X2Go. Please read the ssh man page for more
info on this.

With this little howto, you can test SSH agent authentication request forwarding:

  Place your SSH pubkey on machine-1 and machine-2 (which can be reached via
  machine-1) into the (for this demo) otherwise empty files:

    user-1@machine-1:~user-1/.ssh/authorized_keys

  and

    user-2@machine-2:~user-2/.ssh/authorized_keys

  Return to your local client:

  $ ssh-add [<priv-keyfile>]
  $ pyhoca-gui

  Enable SSH agent forwarding in connection tab of a session profile for
  machine-1. Use a simple TERMINAL session command.

  Connect to user-1@machine-1 and start a session on machine-1

  $ echo $SSH_AUTH_SOCK
  /tmp/ssh-<hash>/agent.<pid>

  $ ssh <user-2>@<machine-2>
  (should work without password)

  For the authentication from user-1@machine-1 to user-2@machine-2 you use an
  SSH agent connection that is tunneled back through Python X2Go to your client
  machine (the machine you run PyHoca-GUI on). So, the SSH agent on your client
  machine serves a challenge/response request from SSH client programs within
  X2Go sessions.

  Note: if you try the above with a GNOME desktop (XFCE probably as well) the
  gnome-keyring will hijack the SSH agent functionality and ignore forwarded
  SSH agent connections. (This normally happens with the x2goserver-xsession
  bin:package installed.)

  Use the below command to disable the SSH agent feature in gnome-keyring (within the
  X2Go Session):

  $ gconftool-2 -s /apps/gnome-keyring/daemon-components/ssh false  --type bool

  After you have applied this gconf change, logout and re-start a new GNOME (or XFCE)
  session. Now SSH agent stuff is handled properly through ssh-agent and the ssh-agent
  should also be aware of SSH agent forwarding connections.
