PAPI Quick Installation Guide
=============================

These instructions let you get a minimal installation of
PAPI up and running quickly in a modern Debian/Ubuntu system.
For the sake of simplicity, we assume you are installing both
PAPI components (AS and PoA), although later we will show you
how to configure each, may be in different computers. We
use the names 'ashost' and 'poahost' as examples. Both may be the
same (localhost, for instance).

These instructions make use of the WAYF (Where Are You From)
capability of PAPI. It means that when you try to access a protected
resource (PoA), you are redirected to the AS to authenticate first, then
you are returned to the PoA, where you (most probably in real life,
certainly in this example) will be granted access. There is another way
for PAPI to work: yoy may access the AS first, and after a successfull
authentication you will be presented with a list of PoAs you can access. This
is usually caled the 'portal mode', while the one using the WAYF is usually
called (surprisingly) the 'WAYF mode'.


$ cd $BUILDDIR
$ tar xzf PAPI-1.4.1.tar.gz
$ cd PAPI-1.4.1
$ perl Makefile.PL

...
You must provide a location for installing the PAPI Authentication
Server software. It must be a directory configured to hold CGI
programs in your Apache installation [/usr/local/apache/cgi-bin]
-> /usr/lib/cgi-bin
...
The program was not able to determine a location for your OpenSSL
installation, required to build PAPI. Please type the full path to
the OpenSSL directory [/usr/local/ssl]
-> /usr
...

* If there are messages about missing Perl modules, install them and do
  it again (you can skip the module Athens::DA if interaction with Athens
  is not a requirement for you).
* If you don't have CGI::Lite, install it (necessary for the AS)

* Usually, this is necessary (for the PoA):
$ ln -s /usr/include/apache-1.3 /usr/include/apache

$ make
$ make install

* It will install:
  /usr/lib/cgi-bin/{AuthServer,AuthServer.cf}
  /usr/local/lib/perl/x.y.z/PAPI/*
  /usr/local/lib/perl/x.y.z/auto/PAPI/*
  /usr/bin/{pdimport,pdexport}
  and several man pages


** In the AS (assuming its ID will be 'MyAS'):

$ mkdir -p /usr/local/PAPI/AS/etc
$ cp $BUILDDIR/PAPI-1.4.1/AS/etc/*html /usr/local/PAPI/AS/etc
$ cp $BUILDDIR/PAPI-1.4.1/AS/etc/Basic.sample.src /usr/local/PAPI/AS/etc/Basic.src

* Now, generate a pair of public/private keys:

$ openssl genrsa -out MyAS_privkey.pem 1024
$ openssl rsa -in MyAS_privkey.pem -pubout -out MyAS_pubkey.pem

$ mv MyAS_privkey.pem /usr/local/PAPI/AS/etc

* Send the MyAS_pubkey.pem to all the servers with PoAs that are going
  to use our AS (in these systems it must be installed as 
  /usr/local/PAPI/PoA/KEYS/MyAS_pubkey.pem).

- If you are going to configure a PoA in this system:
  $ mkdir -p /usr/local/PAPI/PoA/KEYS
  $ cp MyAS_pubkey.pem /usr/local/PAPI/PoA/KEYS/MyAS_pubkey.pem

* Edit /usr/lib/cgi-bin/AuthServer.cf:

- Make sure this line exists:
use PAPI::BasicLog;

$$cfg{workingDirectory} = '/usr/local/PAPI/AS/etc';

# This SHOULD be https, but for testing you can use http
$$cfg{asLocation} = 'http://ashost/cgi-bin/AuthServer';
$$cfg{serverID} = 'MyAS';
$$cfg{privateKey} = 'MyAS_privkey.pem';

- Generate this value using, for example, md5sum:
- cat `find /var/tmp -type f -print` | md5sum | cut -c1-32
$$cfg{symKey} = "................................"

- For the first tests:
$$cfg{basicAuthDB} = "Basic.pdb"
...
$$cfg{authenticationHook} = \&PAPI::BasicAuth::VerifyUser;
$$cfg{credentialHook}     = \&PAPI::BasicAuth::AllSites;
$$cfg{attrRequestHook}    = \&PAPI::BasicAuth::AllSiteAttributes;

With BasicAuth, everything is configured in a simple file: Basic.pdb

- You can leave these commented out. They are tipically defined to
- point to red and green balls when you use the portal mode instead
- of WAYF, as we do in this sample setup.
#$$cfg{acceptURL} = 'http://as.papi.dom.ain/accept-file';
#$$cfg{rejectURL} = 'http://as.papi.dom.ain/reject-file';


- For the first tests, you can comment:
#$$cfg{splitModeURL} = ...
#$$cfg{splitModeParamList} = ...

- Logging:
$$cfg{logHook} = \&PAPI::BasicLog::FileLog;
$$cfg{logFile} = "/var/tmp/PAPIAS.log";

* Define at least one user and one site (PoA) for BasicAuth to use
  In /usr/local/PAPI/AS/etc/Basic.src append the following lines 
  IMPORTANT: Change 'poahost'! It must match the name you use to access
             the PoA:

<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
# User 'papitest', password: 'papitest'
user::papitest::hw0rgZVZz0QRs::::::
#
site::PAPI_test_site::PAPI Test site::http://poahost::/PAPI/cookie_handler.cgi::1800::TestPoA::/papi::index.html::
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>

$ cd /usr/local/PAPI/AS/etc
$ pdimport -n -s Basic.src Basic.pdb


** In the PoA:
  If you have not done this before:
- mkdir -p /usr/local/PAPI/PoA/KEYS
- mv ..../MyAS_pubkey.pem /usr/local/PAPI/PoA/KEYS
  (The name *MUST* be the ID of the AS with "_pubkey.pem" appended).

- ps -ef | md5sum | cut -c1-32 > /usr/local/PAPI/PoA/lkey
- cat /var/log/messages | md5sum | cut -c1-32 > /usr/local/PAPI/PoA/hkey

- chown -R www-data /usr/local/PAPI

- Configure one simple PoA. At the end of /etc/apache/httpd.conf:

  include "papi.conf"

- Contents of the file /etc/apache/papi.conf (change 'ashost'):

<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
PerlModule PAPI::Conf
<PAPI_Main>
  Service_ID test_PoA
  Debug 1
  HKEY_File     /usr/local/PAPI/PoA/hkey
  LKEY_File     /usr/local/PAPI/PoA/lkey
  Lcook_Timeout 60
  CRC_Timeout   30
  URL_Timeout   200
  Auth_Location /PAPI/cookie_handler.cgi
  Accept_File   /usr/local/PAPI/PoA/blueball.png
  Reject_File   /usr/local/PAPI/PoA/redball.png
  Pubkeys_Path  /usr/local/PAPI/PoA/KEYS
  Hcook_DB      /usr/local/PAPI/PoA/hcook.db
  PAPI_AS       MyAS http://ashost/cgi-bin/AuthServer Test AuthServer
</PAPI_Main>

<Location /papi>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
      Service_ID TestPoA
      GPoA_URL wayf:built-in
      Req_DB /usr/local/PAPI/PoA/req_TestPoa
    </PAPI_Local>
</Location>
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>


* In the PoA server (poahost), create the protected pages:

$ mkdir /var/www/papi
$ cat <<END > /var/www/papi/index.html
<html>
You have reached this PoA !
</html>
END

* In the PoA server (poahost):

$ /etc/init.d/apache restart

* In any browser, try to access:

http://poahost/papi/index.html

Your browser will be redirected to the AS for authentication and
then to the protected pages. To authenticate use papitest/papitest


*** Configuration of a GPoA

A GPoA is a special kind of PoA that sits between regular PoAs
and an AS. You can configure the PoAs so that they don't 
communicate with the AS, but with the GPoA, and in that case
you don't have to configure the PoAs in the AS, just the
GPoA. It is specially useful because some implementations of
the PAPI protocol (such as phpPoA and the PAPIFilter for
java based resources) rely on a GPoA to work.

The only differences between a GPoA and a regular PoA are:

- You must generate a pair of public and private keys
  for the GPoA
- In the Apache configuration of a GPoA you must declare
  the GPoA_Priv_Key directive
- The public key of the GPoA must be installed by the PoAs
  using it

A regular PoA can use a GPoA just declaring its URL in
the GPoA_URL Apache directive.

$ openssl genrsa -out GPoA_privkey.pem 1024
$ openssl rsa -in GPoA_privkey.pem -pubout -out GPoA_pubkey.pem
$ mv GPoA_pubkey.pem /usr/local/PAPI/PoA/KEYS/_GPoA_pubkey.pem
  (the directory must math the Pubkeys_Path Apache directive
   and the filename must be exactly that)
$ mkdir /usr/local/PAPI/GPoA
$ mv GPoA_privkey.pem /usr/local/PAPI/GPoA
  (you can put it anywhere, you just have to declare its
   path in the GPoA_Priv_Key Apache directive inside the 
   GPoA configuration).

Append these lines to the Apache configuration and restart Apache:

<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
<Location /gpoa>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
      Service_ID TestGPoA
      GPoA_URL wayf:built-in
      Req_DB /usr/local/PAPI/PoA/req_TestGPoA
	  GPoA_Priv_Key /usr/local/PAPI/GPoA/GPoA_privkey.pem
    </PAPI_Local>
</Location>
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>

Next you must declare the GPoA in the Basic.src file as any
regular PoA (Remember to change 'poahost'! ):

<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
site::PAPI_test_gpoa::PAPI Test GPoA::http://poahost::/PAPI/cookie_handler.cgi::1800::TestGPoA::/gpoa::index.html::
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>


* Using the GPoA

The previously defined PoA can use this GPoA just
declaring:

GPoA_URL http://poahost/gpoa/PAPI/cookie_handler.cgi

instead of 'GPoA_URL wayf:built-in'
For example (create /var/www/papi_gpoa/index.html and change 'poahost'!):

<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>
<Location /papi_gpoa>
    PerlSendHeader On
    PerlAccessHandler PAPI::Main
    <PAPI_Local>
      Service_ID TestPoA_GPoA
      GPoA_URL http://poahost/gpoa/PAPI/cookie_handler.cgi
      Req_DB /usr/local/PAPI/PoA/req_TestPoa_GPoA
    </PAPI_Local>
</Location>
<<<<<<<<<<<<<<<<<<<<<< CUT HERE >>>>>>>>>>>>>>>>>>>>>>

This way you don't have to declare this PoA in Basic.src

** Finally

* Watch the logs!
- Messages generated by the AS will go to /var/tmp/PAPIAS.log
- Messages generated by the PoA go to the Apache error_log

* If something goes wrong, do not forget to clear the cookies
  before starting over!