PAPI Tomcat Filter: Installation Notes
--------------------------------------

If you are reading this file, it means that you have successfully downloaded and unpackaged the PAPIFilter for Tomcat distribution. Please make sure that the distribution includes the required files, as defined in the README.txt file.

DEPENDENCIES
------------

- Java SE 5.0 or higher;
- The Apache Commons Collections, version 3.2 or greater. You can download it from: http://commons.apache.org/downloads/download_collections.cgi
- The Apache log4j, version 1.25 or greater. You can download it from: http://logging.apache.org/log4j/1.2/download.html
- The Bouncy Castle Provider package. You may download this package from: http://www.bouncycastle.org/download/bcprov-jdk15-132.jar

These three jar dependencies should be installed in the $CATALINA_HOME/common/lib directory.

INSTALLATION PROCEDURE
----------------------

1. Locate your Tomcat installation directory; from now onwards we'll refer to it as $CATALINA_HOME;
2. Copy the jars file papiee-crypt-1.0.jar and papiee-papiv1-1.0.jar in the $CATALINA_HOME/shared/lib directory;
3. Place the configuration file of this filter where you wish, and change its content according to your needings (see "CONFIGURATION FILE" information below);
4. To make PAPI filter control a certain Tomcat location, include the following lines in the corresponding web.xml file (note that the defined filters will be applied in order of appearance):

    <filter>
        <filter-name>PAPI Filter</filter-name>
        <filter-class>es.rediris.papi.filter.PAPIFilter</filter-class>
        <init-param>
            <param-name>configfile</param-name>
            <param-value>#location of the file#</param-value>
        </init-param>
    </filter>

5. Define a mapping for the filter, and a regular expression defining which applications the filter is defined for ('/* for all):

    <filter-mapping>
        <filter-name>PAPI Filter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

For more information about configuring web.xml, please refer to the Tomcat configuration.

CONFIGURATION FILE
------------------

The configuration file is an standard XML Properties file. 
Basically, if you want a quick deployment of the PAPIFilter, you can use the following document:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<!-- Configure these values -->
	<entry key="poa.lkey_filename">/home/papi/papifilter/keys/lkey</entry>
	<entry key="poa.hkey_filename">/home/papi/papifilter/keys/hkey</entry>
	<entry key="poa.service_id">My_PoA</entry>
	<entry key="poa.location">/jsp-examples/</entry>  
	<entry key="poa.parentgpoa.uri">http://server/GPoA/papiPoA</entry> 
	<entry key="poa.parentgpoa.pubkey_filename">/home/papi/papifilter/keys/_GPoA_pubkey.pem</entry>
	<entry key="poa.fileregistry.filename">/home/papi/papifilter/registry/fileregistry.txt</entry>
<!-- Default values -->
	<entry key="poa.papi_filter">.* => accept</entry> 
	<entry key="poa.lcook_timeout">300000</entry>
	<entry key="poa.url_timeout">100000</entry>
	<entry key="poa.registry">FileRegistry</entry>
	<entry key="poa.token_handler">plain</entry>
    <entry key="papifilter.cookie_maxage">604800</entry>
	<entry key="papifilter.reject_message">The user has no valid credentials for this resource.</entry>
	<entry key="papifilter.hcook_name">hcook</entry>
	<entry key="papifilter.lcook_name">lcook</entry>
	<entry key="papi.assert_separator">,</entry>
	<entry key="papi.attr_separator">:</entry>
	<entry key="papi.value_assert_separator">=</entry>
	<entry key="papi.multivalue_assert_separator">-</entry>
	<entry key="papi.issuer_assert_separator">@</entry>
</properties>

In order to configure your PAPI filter, you should define the following parameters:

+ Configuring the PAPI Filter itself:
	- papifilter.hcook_name: specifies the name of the cooking which holding the value of the hcook token.
		* Example:
			<entry key="papifilter.hcook_name">hcook</entry>
			
	- papifilter.lcook_name: specifies the name of the cooking which holding the value of the lcook token.
		* Example:
			<entry key="papifilter.lcook_name">lcook</entry>

	- papifilter.reject_message: specifies which error message the PAPIFilter is going to send when the user hasn't valid credentials for accessing the protected resource.
		* Example:
			<entry key="papifilter.reject_message">The user has no valid credentials for this resource.</entry>

+ Configuring the PoA behaviour:
	- poa.lkey_filename: specifies the path of the file containing the lkey
		* Example:
			<entry key="poa.lkey_filename">/home/papi/papifilter/keys/lkey</entry>

	- poa.hkey_filename: specifies the path of the file containing the hkey
		* Example:
			<entry key="poa.hkey_filename">/home/papi/papifilter/keys/hkey</entry>

	- poa.service_id: specifies the service ID of the PoA
		* Example:
			<entry key="poa.service_id">My_PoA</entry>

	- poa.location: specifies the root location (in the web server) of the PoA
		* Example:
			<entry key="poa.location">/jsp-examples/</entry>

	- poa.hcook_maxage: specifies the timelife of the hcook token.
		* Example:
			<entry key="poa.hcook_maxage">604800</entry>

	- poa.lcook_timeout: specifies the timelife of the lcook token.
		* Example:
			<entry key="poa.lcook_timeout">300000</entry>

	- poa.url_timeout: specifies the timelife of the token received in a Cheked response from a GPoA.
		* Example:
			<entry key="poa.lcook_timeout">100000</entry>

	- poa.papi_filter: specifies a list of filters (separated by commas) for checking the user rights accessing to the protected resource. The format of a filter is 'regular expression => [accept|reject]'. That regular expression is matched with the attributes of the user.
		* Example:
			<entry key="poa.lcook_timeout">mail=*.@domain.net => accept,.* => reject</entry>

	- poa.parentgpoa.uri: specifies the URI of a GPoA parent.
		* Example:
			<entry key="poa.lcook_timeout">http://server/GPoA/papiPoA</entry>

	- poa.parentgpoa.pubkey_filename: specifies the path of the file containing the public key, in PEM format, of the GPoA.
		* Example:
			<entry key="poa.parentgpoa.pubkey_filename">/home/papi/papifilter/keys/_GPoA_pubkey.pem</entry>

	- poa.registry: specifies which registry service the PoA has to use. At the moment, the one based on files is only available.
		* Example:
			<entry key="poa.registry">FileRegistry</entry>

	- poa.token_handler: specifies which token handler the registry service has to use. At the moment, the plain one is only available.
		* Example:
			<entry key="poa.token_handler">plain</entry>

+ Configuring the file registry:
	- poa.fileregistry.filename: specifies which token handler the registry service has to use. At the moment, the plain one is only available.
		* Example:
			<entry key="poa.fileregistry.filename">/home/papi/papifilter/registry/fileregistry.txt</entry>

+ Configuring the PAPI behaviour:
	<entry key="papi.multivalue_assert_separator">-</entry>
	<entry key="papi.issuer_assert_separator">@</entry>
	- papi.assert_separator: specifies which character(s) the PoA uses as a separator in a list of attributes.
		* Example:
			<entry key="papi.assert_separator">,</entry>

	- papi.attr_separator: specifies which character(s) the PoA uses as a separator in a list of elements of a token.
		* Example:
			<entry key="papi.attr_separator">:</entry>

	- papi.value_assert_separator: specifies which character(s) the PoA uses as a separator in a pair of atttribute name and attribute value.
		* Example:
			<entry key="papi.value_assert_separator">=</entry>

	- papi.multivalue_assert_separator: specifies which character(s) the PoA uses as a separator in a list of values of an attribute.
		* Example:
			<entry key="papi.multivalue_assert_separator">-</entry>

	- papi.issuer_assert_separator: specifies which character(s) the PoA uses as a separator between the list of attributes and the ID of the Identity Provider.
		* Example:
			<entry key="papi.issuer_assert_separator">@</entry>