This is the README file for PAM-module pam_rsa. Read it before
use and also read man pam_rsa(8).

----------------------------------------------------------------

Q1) What is pam_rsa?

pam_rsa is a PAM-module (Pluggable Authentication Module) for
local authentication. It works on Linux and Solaris, and 
will probably work on other systems too provided that their 
PAM-implementations are compatible enough.

The authentication method is based on RSA keypairs. RSA 
public keys (contained in X509 certificates in PEM-format) are 
permanently stored on a target computer. User authenticates with 
the RSA private key that corresponds to his stored RSA public key.

The traditional pam_unix_auth authentication model relies on
passwords that users have memorized. The hashed passwords are
usually stored in /etc/shadow. The pam_rsa module can eliminate
the memorizing of passwords and typing them in when authenticating 
locally. 

However, the general PAM framework is pretty flexible, so you 
can define authenticating with an RSA keypair to be sufficient
by itself, but you can also strengthen the existing password-based 
authentication model by requiring both a correct password and 
a successful pam_rsa authentication.

----------------------------------------------------------------

Q2) How can a user enter his RSA private key when authenticating? 

One possible way is to store the private key on a removable 
USB memory stick and carry it with you, BUT MAKE SURE YOU NEVER 
LOSE YOUR PRIVATE KEY! Passphrase encrypted RSA private 
keys are recommended (unless you are absolutely sure that
you know what you are doing).

As a prerequisite, the target host should be set up in 
a such a way that the operating system will automatically 
detect the memory stick when it is inserted into a USB port. 

However, it is not sufficient that the OS kernel detects the 
USB device. The pam_rsa module must have access to the 
file system in order to read the RSA private key, so the 
USB memory stick must be automatically mounted too. One way 
to arrange automatic mounting (and unmounting) is to use 
automount (a.k.a. autofs).

----------------------------------------------------------------

Q3) Do I have to use store my private keys on a USB memory stick?

No. The module does not care what the underlying media is
as long as it can access the file system. 

It would be impractical, but in theory the private keys could 
be stored even on, say, a CD-RW. 

----------------------------------------------------------------

Q4) Can I use pam_rsa for authenticating to PAM-aware remote services 
      like SMTP, IMAP or POP? 

No. The pam_rsa module would expect to see your private key
on the remote server, and I suppose this is not what you had
in mind. The module is for local authentication only. (Of
course if you have a *local* IMAP service, then the answer
is affirmative).

----------------------------------------------------------------

Q5) Are there any risks in configuring the general PAM-framework?

Sure. Especially if you are not familiar with configuring 
PAM-systems, you can initially render some services 
unusable, unsafe, or both, by messing up with their 
configurations. 

There are two main stages in successfully setting 
up PAM. On the one hand there is the system's general 
PAM configuration that dictates how certain services 
(e.g. chsh, chfn, gdm, login) perform authentication. 

On the other hand, the individual PAM-modules may 
require different arguments and individual configuration  
files to work properly. Depending on a specific PAM-module, 
the setup can be more or less time consuming (for instance, 
if you use pam_ldap or pam_radius, you need not only a proper 
module configuration, but also a safely accessible and 
working LDAP- or RADIUS-server that matches the module 
settings).

----------------------------------------------------------------

Q6) How about the pam_rsa module and its particular risks?

Fortunately pam_rsa is easy to configure and should not
require much external work. Once the module is correctly 
configured, adding users is just a matter of generating 
RSA keypairs in a correct format, naming them as pam_rsa
expects, storing them in proper directories, and then of 
course following good security practices (some of which are
described below).

If you are not familiar with PAM, before trying 
to use pam_rsa, I strongly suggest that you first gather 
a basic understanding of how the general PAM-framework 
works and how it should be configured. On modern Linux 
hosts, it is usually the directory /etc/pam.d that 
contains general configurations for PAM-aware services. 
On Solaris (and optionally on Linux), the whole PAM-framework 
configuration is in a single file called /etc/pam.conf.

So, to answer the question about risks, if you do not know
what you are doing, you may end up with a system that never
allows logins at all, or with a system that allows logins
when it should not - an equivalently horrific alternative
if the host contains your sensitive private data.

It is possible that pam_rsa module itself contains 
unknown security flaws. In such a case, even completely correct 
configurations might be vulnerable to attacks. The source code
is available, so you can check out if it is secure enough.
    
If your private key is on a USB memory stick, you must take 
extremely good care of it, because if you lose it, somebody 
could authenticate as you. In other words: NEVER EVER EXPOSE 
YOUR PRIVATE KEY TO ANYONE BUT YOURSELF. Losing the private 
key can also imply that you can no longer authenticate to 
services that have been configured to always require 
pam_rsa in order to succeed. 

If your RSA private key is protected by a passphrase, then
the attacker would have to know the passphrase as well, so 
using passphrases is definitely safer than using plain
text private keys.

You must take care of the fact that the target computer is
not a multi-user machine. For example, if you have all kinds
of users logged in remotely (say, via SSH), they might be
able to access your USB memory stick while it is inserted, and
then they could steal your private RSA key. Or there may already
be users who have gained superuser privileges and are able to 
access all memory areas, create malicious kernel modules or do
whatever they wish - without you knowing it (in that case you
already have lots of problems even without pam_rsa!).

DO NOT USE THIS PAM MODULE ON A HOST THAT HAS MANY USERS
LOGGED IN SIMULTANEOUSLY!!! YOUR SHARED BOX IS NOT THE RIGHT
ONE TO USE IT!

To summarize:

a) Understand how the general PAM-framework should be configured
(e.g. /etc/pam.d/{service} or /etc/pam.conf)

b) Understand how the pam_rsa PAM-module should be configured.
This is the easy part, since the module is simple and has
only a few options. (e.g. /etc/security/pam_rsa.conf and 
module's arguments)
       
c) Take good care of your private key. It highly recommended
that you create a unique RSA keypair for each host you
intend to use pam_rsa on, and never use the private keys
for any other purpose than logging in to a particular host.
That way, if you lose the key, your other services will
not be compromised as well. It is also recommended that
the RSA private key will be passphrase protected. 

UNLESS YOU ARE ABSOLUTELY SURE THAT PLAIN TEXT PRIVATE KEY IS
OKAY FOR YOUR PURPOSES, ALWAYS USE PASSPHRASES TO ENCRYPT YOUR
RSA PRIVATE KEYS.

d) Do not use pam_rsa on a host that allows several users to be
simultaneously logged in

----------------------------------------------------------------
 
Q7) How do I compile, configure and install the pam_rsa module?

If you have the source distribution, you can try:

    ./configure
    make 
    make install


That should work on many Linux platforms provided you have
installed GCC, openssl-devel and pam-devel. If you have a
binary RPM suitable for your OS, try the usual:

    rpm -Uvh pam_rsa-x.y-z-arch.rpm

If you have a source RPM and want to generate a binary
RPM, then try:

    rpmbuild --rebuild pam_rsa-x.y-z.src.rpm
     

Compiling on Solaris probably requires some tweaking. I have tested 
pam_rsa only on Sun Sparc Solaris 8 (SunOS 5.8) with the commercial 
Sun Workshop Pro C Compiler. On that host, OpenSSL library had been 
installed in /usr/local/ssl/lib and the corresponding headers 
in /usr/local/ssl/include. 

The operating system had also been patched to have /dev/urandom, 
because OpenSSL often needs to have entropy available. There is an 
official /dev/urandom patch by Sun Microsystems, and also a different 
unofficial one.

After that I set some tcsh environment variables:

    tcsh% setenv CC /opt/SUNWSpro/bin/cc
    tcsh% setenv CFLAGS "-I/usr/local/ssl/include"
    tcsh% setenv CPPFLAGS "-I/usr/local/ssl/include"
    tcsh% setenv LDFLAGS "-L/usr/local/ssl/lib -R/usr/local/ssl/lib"

Equivalents for sh-style shells would be:

    bash$ export CC=/opt/SUNWSpro/bin/cc
    bash$ export CFLAGS="-I/usr/local/ssl/include"
    bash$ export CPPFLAGS="-I/usr/local/ssl/include"
    bash$ export LDFLAGS="-L/usr/local/ssl/lib -R/usr/local/ssl/lib"

Running:

    tcsh% ./configure

would give the following warning message:

+++++++++++++++++++sample begins+++++++++++++++++++++++++

checking security/pam_appl.h usability... yes
checking security/pam_appl.h presence... yes
checking for security/pam_appl.h... yes
checking security/pam_modules.h usability... no
checking security/pam_modules.h presence... yes
configure: WARNING: security/pam_modules.h: present but cannot be compiled
configure: WARNING: security/pam_modules.h:     check for missing prerequisite headers?
configure: WARNING: security/pam_modules.h: see the Autoconf documentation
configure: WARNING: security/pam_modules.h:     section "Present But Cannot Be Compiled"
configure: WARNING: security/pam_modules.h: proceeding with the preprocessor's result
configure: WARNING: security/pam_modules.h: in the future, the compiler will take precedence
configure: WARNING:     ## ------------------------------------------------ ##
configure: WARNING:     ## Report this to hyperllama@laamanaama.helsinki.fi ##
configure: WARNING:     ## ------------------------------------------------ ##
checking for security/pam_modules.h... yes

+++++++++++++++++++++sample ends+++++++++++++++++++++++++

The reason for that warning is unknown to me, since the
/usr/include/security/pam_modules.h seems perfectly okay.

As I am already aware of this bug, please do not report it unless
you can give some advice on how to fix it.

Then I just did the usual:

    tcsh% make
    tcsh% make install

On that host the working pam_rsa.so module's DLL dependencies are:

    tcsh% ldd /lib/security/pam_rsa.so 
            libcrypto.so.0.9.7 =>    /usr/local/ssl/lib/libcrypto.so.0.9.7
            libpam.so.1 =>   /usr/lib/libpam.so.1
            libpthread.so.1 =>       /usr/lib/libpthread.so.1
            libsocket.so.1 =>        /usr/lib/libsocket.so.1
            libnsl.so.1 =>   /usr/lib/libnsl.so.1
            libdl.so.1 =>    /usr/lib/libdl.so.1
            libc.so.1 =>     /usr/lib/libc.so.1
            libcmd.so.1 =>   /usr/lib/libcmd.so.1
            libmp.so.2 =>    /usr/lib/libmp.so.2
            libthread.so.1 =>        /usr/lib/libthread.so.1
            /usr/platform/SUNW,Sun-Fire-280R/lib/libc_psr.so.1


If you have Solaris GCC or some other compiler, prepare for 
doing tweaking on your own.

----------------------------------------------------------------

Q8) Once pam_rsa module is installed, how do I configure it?

The file doc/pam_rsa.conf.EXAMPLE contains a sample configuration
for the module. The configuration file is described in the 
manual page (man pam_rsa(8)).

----------------------------------------------------------------

Q9) If I wish to use automounter (autofs), what should I do?

Take a look at the examples and modify as appropriate for
your environment:

        doc/auto.master.EXAMPLE
        doc/auto.pamrsa.EXAMPLE

NOTE: If you use GNOME Desktop *and* automounter, you
may have to disable GDM's automounting 
(Preferences -> Removable Storage -> Do Not Automount),

See also:
 automount(8), autofs(5), autofs(8), auto.master(5)

----------------------------------------------------------------

Q10) How can I create RSA keypairs for pam_rsa?

man pamrsakp(8). man pam_rsa(8).

----------------------------------------------------------------

