pam_sshauth
===========

pam_sshauth is a PAM library that allows you to authenticate a local machine
based on being able to ssh into a remote one.  It essentially ties a local
pam login to a remote ssh login.

Requirements:
-------------

pam_sshauth requires:

    * libssh version 4 or better

Configuration:
--------------

The pam_sshauth module understands 4 pam command line options:

  * host=<hostname.or.ip>
  * port=<port>
  * nostrict
  * authtries=<number>

So, in the pam file for the service you're using pam_sshauth with, you could
specify:

auth    required        pam_sshauth.so host=myhost.com port=128 nostrict

The "nostrict" option allows the pam_sshauth module, upon ssh'ing into a host
you don't currently have the host key for, to ask you, via the pam prompts
mechanism, if you'd like to add the current host to your host keys.  The
default is that this option will not be offered to you, and any attempt to
authenticate against a machine you don't have the host key for will fail.

The pam_sshauth module will ALSO check for the presence of two environment
variables: PAM_SSHAUTH_HOST and PAM_SSHAUTH_PORT.  It isn't necessary on either
the pam command line OR the environment variable to set the port: it will
default to 22.  However, if neither the pam command host= parameter or the
PAM_SSHAUTH_HOST environment variable are set, the authentication will fail.

The pam_sshauth module can handle password expiry, via ssh's "kbint" (keyboard
interactive) method of authentication.  It will detect if the authentication
server's sshd supports this option.

By default, sshd comes configured with simple password authentication.  If
you'd like password expiry to work, you need to set:

ChallengeResponseAuthentication yes

in your /etc/ssh/sshd_config file on the server.

Interactions with ssh:
----------------------

One of the primary goals with pam_sshauth is to create an ssh "Master socket"
which can thereafter be used to launch programs on the remote system.  The
pam_sshauth library contains no method to do this directly, for the sake of
simplicity.  Rather, we provide a helper which can be used via the SSH-ASKPASS
mechanism, as well as an example script which can be used in conjunction with
pam_exec to create the tunnel.

The shm_askpass program is an SSH-ASKPASS compliant program which can accept a
password on it's stdin, and store it in POSIX shared memory.  Then, it can be
called via ssh using the SSH-ASKPASS mechanism, at which point it provides the
password, zeros the password in shared memory, and deletes the shared memory
segment.

In the examples directory of this archive I've provided an example session
script for use with pam_exec which will handle storing the password, launching
the ssh Master socket, and closing the socket down on pam session completion.


Testing:
--------

To test, create an example service file in /etc/pam.d.  You can use the
"pamtest" utility provided by the libpam_dotfile package (check your distro) to
test the libpam_sshauth module.

The service file should contain the following lines:

auth    required        pam_sshauth.so host=127.0.0.1  # or wherever
auth    required        pam_exec.so expose_authtok /usr/bin/ltsp-session
session required        pam_exec.so /usr/bin/ltsp-session

Copy the "examples/ltsp-session" file to /usr/bin, or somewhere else if you'd
prefer, and just modify the pam_exec lines above accordingly.

Build the source with:

./configure --prefix=/usr && make && sudo make install

Then, using libpam-dotfile's pamtest utility:

pamtest <service> user

You should see something along the lines of:

sbalneav@phobos:~$ pamtest flarp scbal
Trying to authenticate <sbalneav> for service <flarp>.
Password:
Authentication successful.

pam_sshauth logs to authlog:

Jan 10 21:29:40 phobos pam_sshauth[22724]: Beginning authentication.
Jan 10 21:29:40 phobos pam_sshauth[22724]: User: scbal Host 127.0.0.1
Jan 10 21:29:40 phobos pam_sshauth[22724]: Auth method PASSWORD
Jan 10 21:29:40 phobos pam_sshauth[22724]: Auth method INTERACTIVE
Jan 10 21:29:40 phobos pam_sshauth[22724]: Performing keyboard interactive authentication
Jan 10 21:29:45 phobos sshd[22725]: Accepted keyboard-interactive/pam for scbal from 127.0.0.1 port 56984 ssh2
Jan 10 21:29:45 phobos sshd[22725]: pam_unix(sshd:session): session opened for user scbal by (uid=0)
Jan 10 21:29:45 phobos sshd[22783]: Received disconnect from 127.0.0.1: 11: Bye Bye
Jan 10 21:29:45 phobos sshd[22725]: pam_unix(sshd:session): session closed for user scbal

LICENSE
-------

pam_sshauth is licensed under the GNU GPL 2 or later license.
