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 directory $HOME/.ssh/login-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.

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/.

Finally, pam_ssh honours TMPDIR before spawning ssh-agent, namely
ssh-agent is asked to place its agent file in TMPDIR. pam_tmpdir
from the libpam-tmpdir can be used to set up TMPDIR as follows:

  ...
  @include common-session
  session optional pam_tmpdir.so
  session optional pam_ssh.so
  ...


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