==============================================================================
pGina PAM Server - A PAM-Aware Unix Daemon for pGina
Copyright (C) 2003 Nathan Yocom, Jiho Kim

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Email: nate.yocom@xpasystems.com
Web: http://pgina.xpasystems.com
Snail Mail:
  Nathan Yocom 
  9 Evergreen Farms Rd.
  Scarborough, ME 04074
  Phone: 207-450-4948
==============================================================================


== Requirements ==
In order to compile this daemon, you must have the following libraries:
	- OpenSSL 0.9.7a or higher (http://www.openssl.org)
	- PAM - Commonly available by default
	- GCC 2.95.2 or higher
	- Perl (Optional: used to create certificate file)


== Compilation and Installation ==
Easy:
./configure
make
make install


== Upgrading an older Installation ==
Easy:
Make sure pgina_pam is not running
./configure
make
make upgrade

If you are upgrading to 1.0 it is recommended that you do a full make install
as this will ensure that the proper hosts/groups files are installed.  If you
don't want to risk it, make upgrade will update the pgina_pam binary, then you
must copy all the files from the authasst.conf/* directory to /etc/pgina_pam.

;) Enjoy


== I need a certificate?! ==
In order to run this daemon, you need to provide a PEM style certificate with
the associated private key in the same file.  This is done as part of the 
make install step, however, if that breaks (its not the smartest script), or
you dont have Perl generating a self-signed cert yourself is as easy as:

$ openssl req -newkey rsa:2048 -sha1 -keyout root_key.pem -out root_request.pem
# fill in the various things it asks for
$ openssl x509 -req -in root_request.pem -sha1 -extensions v3_ca -signkey \
	 root_key.pem -out root_certificate.pem
# give the pass you used in the previous step
$ cat root_certificate.pem root_key.pem > root.pem
$ openssl req -newkey rsa:2048 -sha1 -keout CA_key.pem -out CA_request.pem
$ openssl x509 -req -in CA_request.pem -sha1 -extensions v3_ca -CA root.pem \
	-CAkey root.pem -CAcreateserial -out CAcert.pem
$ cat CAcert.pem CA_key.pem root_certificate.pem > CA.pem
$ openssl genrsa 2048 > server_key.pem
$ openssl req -new -key server_key.pem -sha1 -out server_request.pem
$ openssl x509 -req -in server_request.pem -sha1 -extensions usr_cert -CA CA.pem \
	-CAkey CA.pem -CAcreateserial -out server_certificate.pem
$ cat server_certificate.pem server_key.pem CAcert.pem root_certificate.pem > \
	server.pem
	
== Common Command line options ==
By default, pgina_pam looks for a certificate in /etc/pgina_pam/cert.pem and 
listens for connections on port 299.  You can change these at runtime with the
-c and -p options respectively:
	
	pgina_pam -c /path/to/certificate.pem  # use different certificate
	pgina_pam -p 9191 	               # use a different port
	pgina_pam -p 9191 -c /path/cert.pem    # change both
	
To view the other available options, run:
	
	pgina_pam -h


== Authasst feature == 
Authasst is short for Authentication Assistant.  It is a shot at
access control to the pgina_pam service, so consider a BETA feature.
The command line option -with-authasst will turn this feature on; the
default is off.

The configuration files for authasst (by default) is located at
/etc/pgina_pam.  There are four (4) files: authasst.allow,
authasst.deny, authasst.hosts, authasst.users.  The path for these
files can be specified with the -allow, -deny, -hostgroups, and
-usergroups command line options, respectively.

authasst.allow and authasst.deny define the access rules.  The format
for the each rule is the same:

	USERGROUP HOSTGROUP

Semantically, this means that the user group USERGROUP is allowed (or
denied) access to the pgina_pam service from the host group HOSTGROUP.
pgina_pam will invoke all deny rules before allow rules, i.e. if there
are conflicting rules, the deny takes precedence.  If there are no
applicable rules, the default is to deny.

authasst.users and authasst.hosts define the user groups and host
groups, respectively.  The format for each definition is the same:

	GROUP (GROUP | MEMBER)*

Take for example:
	
	CHEMSTUDENT	CHEM101 CHEM102 CHEM103 ... bob larry
	CHEM101		student1 student2 student3 student5 ...
	CHEM102		student2 student5 student6 student4 ...
	
student1 through student6 are all in the CHEMSTUDENT group, along with
bob and larry.  In the above example, there is also an implicit
definitino of CHEM103 as an empty group.  See the default config files
for other examples.

Internally, there is no difference between groups and members.
"Members" are just small groups.  It may be wise to use unlikely names
for group names to avoid name collision in the future.  The above
notation where group names are in caps is purely coincidental.  There
is no such requirement.  Just avoid whitespaces in group names.

Authasst has a built-in group ALL that includes all the groups given
in a config file.  ALL will always include every group, even if you
try over override it.

One final technical note about hostnames.  By default, hostnames in
the authasst.hosts file need to be IP addresses or fully qualified
DNS/domain names (FQDN), e.g. 10.10.10.10 or fourtens.xpasystems.com.
For a large installation, this may quickly become very unwieldly.  So,
instead, specify suffixes to be stripped from the FQDN (of the
computer you are connecting from) with the command line line option
-strip-suffixes.  You can specify multiple suffixes by delimiting them
with a comma.


== Debugging ==
If compiled with the --enable-debug option, pgina_pam will log
verbose messages to your syslog.  These can be helpful in debugging
pgina_pam and may be requested by the developers should you have problems.
	

== Questions, comments, feedback, offer help? ==
Email me: nate.yocom@xpasystems.com, or use the online discussion forums
at http://www.xpasystems.com.

== Our thanks ==
David Wolff, Ph.D., for his help in setting up the auto* stuff so you could 
do the standard ./configure; make; make install ;)
	


