
This PAM module provides single sign-on behavior for SSH.  The user
types an SSH passphrase when logging in (probably to GDM, KDM, or XDM)
and is authenticated if the passphrase successfully decrypts the
user's SSH private key.  In the PAM session phase, an ssh-agent
process is started and keys are added.  For the entire session, the
user can SSH to other hosts that accept key authentication without
typing any passwords.

http://sourceforge.net/projects/pam-ssh/


Per-user setup
--------------

pam_ssh will try to decrypt the traditional SSH keys, that is, files
matching $HOME/.ssh/id(entity|_(r|d|ecd)sa).  pam_ssh will also try to
decrypt all keys in the directories $HOME/.ssh/login-keys.d and
$HOME/.ssh/session-keys.d, and (if your system administrator has
configured your system thus) allow you to log in using any of these login
keys. So if you want to log in by using an SSH key passphrase, you should
create a login-keys.d directory and in this directory create (symbolic
links to) all the keys you want to use as login keys. Nevertheless keys
in the directory $HOME/.ssh/login-keys.d with .disabled or .frozen as
suffix are ignored. The handling for keys in $HOME/.ssh/session-keys.d
is similar bot those are not used for login purposes.

All SSH keys that are successfully decrypted will be added to the
ssh-agent.


System-wide setup
-----------------

As system administrator you have to add a line to the PAM script for
each service where you want to use pam_ssh.  For example, to add
pam_ssh to /etc/pam.d/login as a single-sign-on method, change

  ...
  @include common-auth
  ...
  @include common-session
  ...

to

  ...
  @include common-auth
  auth optional pam_ssh.so use_first_pass
  ...
  @include common-session
  session optional pam_ssh.so
  ...

By thus adding ssh-auth after common-auth, ssh-auth can use the user's
password to decrypt the user's traditional SSH keys (identity, id_rsa,
or id_dsa).  This is effectively what is achieved by the default
configuration /usr/share/pam-configs/ssh, see pam-auth-update(8).


Another way to use pam_ssh is to instead change the above
/etc/pam.d/login to

  ...
  auth sufficient pam_ssh.so try_first_pass
  @include common-auth
  ...
  @include common-session
  session optional pam_ssh.so
  ...

which will ask the user for an SSH passphrase if the user has placed
any SSH keys in $HOME/.ssh/login-keys.d/ and then authenticate the
user if the passphrase decrypts any of these keys.  If the passphrase
fails, then PAM will fall back to the normal password authentication.
But notice that this method might leak information about existing
users.  Alternatively it is possible to use a setup similar to

  ...
  auth sufficient pam_unix.so nullok_secure
  auth required pam_ssh.so use_first_pass
  ...
  @include common-session
  session optional pam_ssh.so
  ...

to let each user login with either the unix password or the SSH
passphrase.  But notice that there will be 'failed login' notices in
the log whenever a user uses the passphrase instead of the password.

Yet another way to use pam_ssh is to change /etc/pam.d/login to

  ...
  auth required pam_ssh.so
  ...
  @include common-session
  session optional pam_ssh.so
  ...

which will unconditionally ask the user for a SSH passphrase, and only
authenticate the user if this passphrase decrypts any of the SSH keys
in $HOME/.ssh/login-keys.d/.


See also "man pam_ssh", and
http://content.hccfl.edu/pollock/AUnix2/PAM-Help.htm for a good
introduction to PAM.

 -- Jens Peter Secher <jps@debian.org>, Sun, 28 Feb 2010 12:49:51 +0100
 -- Jerome Benoit <calculus@rezozer.net>, Fri, 3 Jul 2013 14:59:15 +0200
