USAGE
=====
Use this with your cell phone provider's SMTP to SMS gateway and use your phone as a 
"token" device to login remotely from unfamiliar and/or untrusted locations.  SSH is 
a good example.  A one time use password is generated and sent whenever you login 
from an untrusted location.

IMPORTANT:  It does NOT make any sense to use this with an email address that 
is not tied to a physical device or where the email password is the same as 
the login password.  If your passwords are the same then an adversary knows 
your login and your email password and can therefore retrieve the one time 
password and defeat the authentication system.

NOTE: Not all software supports prompting twice for two different passwords, if you
use this in conjunction with a traditional password this could be a problem.

BUILDING/INSTALLING
===================
# install pam development libraries (Debian: libpam0g-dev)
# install libesmtp development libraries (Debian: libesmtp-dev)
# run make
# Copy the library to /lib/security (as root)
cp pam_otpsmtp.so /lib/security
# Copy the config file to /etc and edit it (as root)
cp pam_otpsmtp.conf /etc
vi /etc/pam_otpsmtp.conf
# Modify /etc/pam.d/sshd to use pam_otpsmtp.so
See .PAM configuration. below.
# Enable challenge-response for sshd
See .OpenSSH configuration. below.

PAM configuration
-----------------
Normal:
auth       required     pam_stack.so service=system-auth
auth       required     pam_nologin.so

Modified:
auth       requisite    pam_stack.so service=system-auth
auth       required     /lib/security/pam_otpsmtp.so debug conf=/etc/pam_otpsmtp.conf logfile=/var/log/pam_optsmtp.log
auth       required     pam_nologin.so


OpenSSH configuration
---------------------
/etc/ssh/sshd_config:

ChallengeResponseAuthentication yes
UsePAM yes
UseDNS no

# You may also want to adjust LoginGraceTime to a larger value if your mail server is slow

DEBUGGING
=========
make debug
./pam_otpsmtp_test debug conf=pam_otpsmtp.conf logfile=debug.log