PAPI::ApachePoA - Perl functions to implement a PAPI Point of Access on an Apache server.

DESCRIPTION

This package contains a set of functions to implement a PAPI Point of Access as an Apache mod_perl module. It includes functions to create a PAPI PoA, configure it, evaluate access rights to URLs, generate new encrypted tokens, etc.

The ApachePoA object has the following attributes:

ApacheRequest: Apache request object that is going to be processed.
Domain: Name of the web server this PoA belongs to. This parameter is the ``domain'' field used whenever a cookie is generated.
Loc: Location this PoA controls the access to.
Id: Unique Id assigned to this request. Mainly used for logging purposes.
Hkey: Key to encrypt Hcook tokens with the symmetric encryption algorithm (hex string format).
LKey: Key to encrypt Lcook tokens with the symmetric encryption algorithm (hex string format).
Serv: Internal PAPI name of the service offered by this PoA. It identifies the PoA among the others running in the same Apache server.
Lcook_Timeout: Period of time during which Lcook tokens are valid, in seconds.
CRC_Timeout: Period of time during which URL requests with Hcook tokens containing an old random control block are considered valid by this PoA, in seconds.
URL_Timeout: Period of time (in seconds) during which a signed URL generated by an authentication server is valid. This time is measured from the moment the authentication server created the signed URL.
MaxTtl: Maximum time to live (in seconds) to be assigned to access tokens (cookies) by this PoA. Requests coming from any AS asking for longer times will be cut to this value.
Hcook_DB: DB-File where this PoA is going to record Hcook tokens and their properties.
Accept_File: Default object to be sent to the user's browser when an action (LOGIN, TEST, LOGOUT) is accepted.
Reject_File: Default object to be sent to the user's browser when an action is rejected.
Pubkeys_Path: Directory where public keys of the authentication servers are stored.
Auth_Location: URI for dealing with direct requests from PAPI authentication servers.
signoffLocs: Reference to an array containing the signoff locations and procedures.
PassUrlPatterns: Reference to an array containing a list of regular expressions. If the requested URL matches any of them, the PAPI PoA will not perform any further checking, and direct access will be automatically granted. Bear in mind that, in the case of a rewriting proxy, this means that proxying will not be performed either.
Hcook_Handler: URIs matching the regular expression defined here will cause the creation of an Apache note (with identifier PAPIHcook) and the addition of an extra header to the request (called X-PAPI-Hcook), holding the current value of the token contained into Hcook.
HcookGen: If set, the function that is identified by its value is called to generate the actual content of the access tokens. This function will receive the contents of the assertion received from the AS or the GPoA, and the identifier of the AS that originated it.
ases: Reference to a hash containing the PAPI authentication servers that are valid for this PoA.
filters: Reference to an array containing filters that are applicable at this PoA. These filters are applied on user assertions received from any AS.
cookieRejects: Reference to an array containing cookie filters that are applicable at this PoA. These filters are applied on the content of access tokens.
RwUser: A regular expression substitution applied by this PoA to the user assertions it receives, prior to storing them inside access tokens.
HashUser: If set to 1, do not store the user assertion received from the AS into access tokens. Instead of it, use a hash of the assertion value.
AddressInToken: If set to 1, insert the IP address of the client into the user data conveyed by access tokens, and reject requests coming from non-matching IP addresses.
AttSep: A string containing the characters to be used as separators when extracting pairs (attribute name, attribute value) from assertions.
ValSep: A string containing the characters to be used as separators when identifying attribute names and attribute values inside the assertions.
MxNonceErr: Number of mismatches in the nonce field of access tokens that will be accepted.
registerKey, registerVal: Values use for passing the Hcook data to be stored in the file defined by Hcook_DB.
rawHcook: Value of Hcook prior to any processing, used for passing data to the handler defined by Hcook_Handler.
attrList: When the PoA is evaluating an assertion, it is a reference to an array containing the list of attribute names and values received in the current user assertion.
Debug: If set to 1, debug mode is activated.

The following elements are only applicable to PoAs used to connect to Athens-enabled resources using the mechanisms defined by Athens Devolved Authentication (AthensDA) (see http://www.athensams.net/development/devolved_authentication/ for details):

PADATH_LAA: The location that intiates connection to Athens using LAA mode.
PADATH_HDD: The location in charge of answering Athens queries in HDD mode.
Athens_IID: The Athens institution ID to be used.
Athens_AAP: The URL of the Athens Authentication Point.
Athens_Key: The file storing the key to be used in Athens interactions.
Athens_psa: The attribute (inside the user's assertion) containing the Athens Permission Set.
Athens_uia: The attribute (inside the user's assertion) containing the user identifier to be sent to the Athens Authentication Point.
Athens_TTL: The maximum acceptable shift in the timestamps of data exchanged with the Athens Authentication Point.

The following elements are only applicable to PoAs using an external authorization server based on SPOCP (see http://www.spocp.org/ for details):

SPOCPSrv: The definition of the way to connect to the SPOCP server.
SPOCPAct: The action name to be use when querying the SPOCP server for an authorization decision.
SPOCPAcc: If set to 1, the failure in accessing the SPOCP server is considered a positive response to any authorization query.

The following elements are only applicable to PoAs belonging to a hierarchy of points of access that share a common policy, where initial requests for access are resolved at a parent Groupwide-PoA (a GPoA):

GPoA_URL: The URL for accessing the authorization procedures of the GPoA this PoA is associated with.
Req_DB: DB-File where this PoA is going to store the parameters of requests redirected through its GPoA.

The following elements are only applicable to points of access that implement a Groupwide-PoA (a GPoA) controlling the access to a set of PoAs:

GPoA_Priv_Key: The file where the private key for this GPoA is stored.
PoARw: Reference to an array containing the regular expression substitutions applied by this GPoA to rewrite user data when sending them to requesting child PoAs.
GPoAHashUser: If set to 1, do not send to a requesting child PoA the user data as known to this GPoA. Instead of it, use a hash of the data.

The following elements are only applicable to PoAs controlling the access to external resources:

Remote_Serv: Remote service (base URL) this PoA redirects requests to.
Remote_Dom: Whole remote domain this PoA redirects requests to.
PxIP: If set, defines the local IP address to be used by this PoA.
NoXML: If set to 1, disables XML/XHTML processing by this PoA.
Proxy: If set, the proxy used for accessing remote resources.
redirects: Reference to an array containing the general rules for rewriting URLs in the content received from the remote server .
url_redirects: Reference to an array containing URL rewriting rules applicable to the contents of those requested URLs matching a certain pattern.
postRedirects: Reference to an array containing the general rules for POST data rewriting.
hdRedirects: Reference to an array containing the general rules for HTTP header rewriting.
rqRedirects: Reference to an array containing the general rules for rewriting URLs required by the client.
StripLocation: If set to 1, makes this PoA to strip the local Location value before sending requests to the remote site(s).
RwAll: If set to 1, redirect regular expressions will be applied to the full text of the remote resource.
RewMimeTypes: Blank-separated list of MIME types to which the rewriting engine will be applied.
RewUrlPatterns: Reference to an array containing a list of regular expressions. If the requested URL matches any of them, the rewriting engine will be applied, whatever its content type.
RejUrlPatterns: Reference to an array containing a list of regular expressions. If the requested URL matches any of them, the PAPI proxy will reject to serve the URL, returning a 403 FORBIDDEN code instead.
HttpAuth: Reference to an array containing the HTTP Authentication parameters to be used when accessing the remote server/domain.
formProc: Reference to a hash that contain the definitions for automatic form filling when this PoA accesses the remote server/domain.
EvalPx: If set to 1, the strings used in the contents of HttpAuth, formProc, redirects, rqRedirects, url_redirects, postRedirects, hdRedirects, RewUrlPattern, and RejUrlPatterns are evaluated in the current Perl environment (using the Perl eval function) prior to be applied.
PxCkSize: Defines the size (in bytes) of chunks to be retrieved to the remote site for large content in proxy mode. By default its value is 32 KB.

METHODS

Creation and Initialization

new PAPI::ApachePoA: Creates and returns a new PAPI::ApachePoA object with an automatically assigned Id.
$poa->set_parameters($r): Initializes the object with all the parameters applicable to it in the configuration of the Apache server.; Arguments:; $r: Apache request object that is passed to the handler by Apache.

Trust management

($code,$valid_date)=$poa->test_URL($AS,$DATA): This function validates a request from a PAPI Authentication Server by checking:; 1. Whether the authentication server $AS is valid for this PoA.; 2. Whether this PoA has the public key file for this authentication server.; 3. Whether the data $DATA is signed by the authentication server.; 4. Whether the assertion received inside $DATA is compatible with any applicable filters.; 5. If a SPOCP server is defined, whether the request is acceptable according to the server authorization rules.; If checking procedures succeed, this function returns a list with:; 1. A string containing the access code. The string is built by composing a string derived from the received assertion and the name of the authentication server (in the format derivedString@asName).; 2. The date (in seconds since 1st January 1970) until this access is going to be valid.; If the checking procedures fail, it returns a $valid_date=0.; Arguments:; $AS: String with the name of the authentication server.; $DATA: String signed by the authentication server, containing the request data.
($req_id,$code,$valid_date)=$poa->test_GPoA_URL($ARGS,$GID): This function validates a request coming back from this PoA's GPoA, once it has been validated by it, by checking:; 1. Whether there is a GPoA defined for this PoA.; 2. Whether the contents of the DATA argument is signed by the GPoA or by an authentication server answering to an ATTREQ operation.; 3. Whether a correct request identifier has been sent back by the GPoA/AS inside the Id_Req argument.; 4. Whether the assertion received inside the DATA argument is compatible with any applicable filters.; 5. If a SPOCP server is defined, whether the request is acceptable according to the server authorization rules.; This function returns a list with:; 1. The request identifier originally assigned prior to redirecting the request to the GPoA or AS.; 2. A string containing the access code. The string is built by composing a string derived from the received assertion and the name of the authentication server (in the format derivedString@asName).; 3. The date (in seconds since 1st January 1970) until this access is going to be valid.; If the checking procedures fail, it returns a $valid_date=0.; Arguments:; $ARGS: A reference to the arguments of the request, that contain the response of the GPoA/AS.; $GID: If the checking is initiated by a response to an ATTREQ operation sent by an AS, this parameter contains its identifier. Otherwise, is left undefined.
$request_data=$poa->load_request($ID): This function returns the original parameters for a request redirected through a GPoA or AS, and that were stored in the DB-File defined in $poa->{'Req_DB'} using identifier $ID. If no such identifier is found or any error occurs, the function returns undef.; Arguments:; $ID: Identifier of the original request. Taken from &test_GPoA_URL.
$poa->save_request($ID,$REQ): This function stores into the DB-File defined in $poa->{'Req_DB'} the parameters of the request defined by $REQ using identifier $ID.; Arguments:; $ID: The identifier to be assigned to the request.; $REQ: The request to be stored, a reference to an Apache request object.

Access token management

($Hcook,$Lcook)=$poa->get_cookies: This function returns a list with the content of the Hcook and Lcook cookies.
$Hcook_cookie=$poa->gen_Hcook($code,$valid_date): This functions returns a Hcook cookie, encrypted with the HKey of the PoA, ready to be sent to the user's browser.; Arguments:; $code: String with the access code. Taken from &test_URL, &test_GPoA_URL, &test_Hcook or &test_Lcook; $valid_date: Date until this access is valid. Taken from &test_URL, &test_GPoA_URL, or &test_Hcook
($code,$valid_date,$temporal,$new_crc,$gpoa_vdate)=$poa->test_Hcook($Hcook): This function validates the content of a Hcook cookie sent by the user's browser by checking:; 1. Whether the string in $Hcook can be decrypted with the HKey of this PoA; 2. Whether the valid date and the random control block inside $Hcook are acceptable.; 3. Whether there is any filter applicable for the access code.; If checks succeed, it returns a list with the access code, the date until the access is valid, and some flags to indicate the processing of these data by the cookie register. If not, it returns a $valid_date<=0.; Arguments:; $Hcook: String with the content of the Hcook cookie.
$Lcook_cookie=$poa->gen_Lcook($code): This functions returns a Lcook cookie, encrypted with the LKey of the PoA, ready to be sent to the user's browser.; Arguments:; $code: String with the access code. Taken form &test_URL, &test_GPoA_URL, &test_Hcook, or &test_Lcook
($code,$ret)=$poa->test_Lcook($Lcook): This function validates the content of a Lcook cookie sent by the user's browser by checking:; 1. Whether the string in $Lcook can be decrypted with the LKey of this PoA.; 2. Whether the time to live of the token has expired.; 3. Whether there is any filter applicable for the access code.; This function returns $ret=1 and the access code in $code if the checks succeed, and $ret=0 otherwise.; Arguments:; $Lcook: String with the content of the Lcook cookie.
($Hcook_cookie,$Lcook_cookie)=$poa->gen_logout_cookies($code): This functions returns a cookie pair (Hcook and Lcook) with blank fields. The effect of sending these Hcook and Lcook to the user's browser is to erase any PAPI authorization tokens for this PoA.; Arguments:; $code: String with the access code. Taken from &test_URL, &test_GPoA_URL, &test_Hcook, or &test_Lcook
$poa->reg_tmp_Hcook
$poa->reg_final_Hcook
$poa->del_Hcook: These three functions manage the Hcook DB-File defined by $poa->{'Hcook_DB'}. The first one makes a temporary registration of the last generated value for Hcook. The second one consolidates the registration once the request is completed by Apache. The last one is used when a non-consolidated value is found inside the Hcook registry because of an incomplete request.

Logging

$poa->error($error_msg)

This function writes the string $error_msg in the server's error log file using Apache ``error'' level.

Arguments:

$error_msg: String to be written in the error log file.

$poa->warning($warning_msg)

This function writes the string $warning_msg in the server's error log file using Apache ``warning'' level.

Arguments:

$warning_msg: String to be written in the error log file.

$poa->accesslog($log_msg)

This function writes the string $log_msg in the server's error log file using Apache ``notice'' level. It is also possible to make $log_msg to be written to the server's log file. To do it you have to use a custom LogFormat tag in the Apache configuration file, including references to %{PAPI}n in the format expression, like:

        LogFormat "%h %t \"%r\" %>s\n\t%{PAPI}n" papi
        CustomLog logs/access_log papi

Arguments:

$log_msg: String to be written in the error (and access) log files.

$poa->debug($debug_msg)

This function writes the string $debug_msg in the server's error log file using Apache ``warning'' level. $poa->{'Debug'} must has a non-zero value for this function to have any effect.

Arguments:

$debug_msg: String to be written in the error log file.

DESCRIPTION

METHODS

Creation and Initialization

Trust management

Access token management

Logging

SEE ALSO