PAPI::CertAuth - Perl functions providing PAPI authentication by means of X.509 certificates

SYNOPSIS

Inside the AuthServer.cf file:

 $cfg = \%PAPI::AuthServer::cfgVar;
 
 $$cfg{workingDirectory} = "/usr/local/PAPI/AS/etc";
 
 . . .
 
 $$cfg{authenticationHook} = \&PAPI::CertAuth::Validate;
 # Read user data from LDAP using the certificate subject DN
 $$cfg{credentialHook} =  \&PAPI::LDAPAuth::UserCredentials;
 $$cfg{CertValidateMethod} = "client_DN";
 $$cfg{client_DNPattern}="(dc=dom,dc=ain).*(uniqueIdentifier=.*)";
 # Config variables for using the certificate subject DN within
 # PAPI::LDAPAuth::UserCredentials
 $$cfg{LDAPserver} = "ldap.dom.ain";
 $$cfg{LDAPport} = "389";
 $$cfg{LDAPUSERtemplate} = 'uid=<papi var="PAPIuid"/>';
 $$cfg{LDAPAuthSearchBase} = 'ou=people,dc=dom,dc=ain';
 $$cfg{LDAPsearchBase} = 'dc=papi,dc=dom,dc=ain';

REQUIRES

Time::Local

DESCRIPTION

These functions implement PAPI user authentication by means of X.509 certificates. Credential data provision must use different mechanisms, found in other modules. Since there is a natural binding between X.509 certificates and directory systems, the use of the LDAP authentication procedures is strongly recommended.

The functions do not perform any kind of certificate verification. This is left to the Apache SSL module. Certificate data is read from the standard environment variables that Apache uses to communicate them to its components and matched against the validation criteria defined by the configuration. The use of these functions require configuring Apache to request client certificates by means of the directive SSLVerifyClient and the setting of the option CompatEnvVars in SSLOptions.

Validation criteria

The module supports five different validation criteria to be applied on the received certificate data (and the connection itself). The criteria to be applied are selected by means of the configuration variable CertValidateMethod. This variable contains a list of the validation methods to be used. Each method identifier is separated by spaces. Methods are applied in the same order they appear in the list. If any of them fail, authentication is rejected. Method dentifiers not known to the system cause authenticaton to be rejected. Valid method identifiers are:

remote_addr

The IP address of the client must match one of the IP addresses or networks in the list defined by the configuration variable remote_addrPattern. The general format of this parameter consists of a blank-separated list of IP addresses and networks, as in the following example:

 $$cfg{remote_addrPattern} = "1.2.3.4 5.6.7.8/30 9.10.11.12";

start_date

The certificate must have been issued after the date defined by the start_datePattern configuration variable. Dates must be expressed in the format Month Day hh:mm:ss Year GMT.

end_date

The certificate must have been issued before the date defined by the end_datePattern configuration variable. Dates must be expressed in the format Month Day hh:mm:ss Year GMT.

issuer_DN

The DN of the certification authority that issued the certificate must match against the regular expression defined by the issuer_DNPattern configuration variable.

client_DN

The subject DN of the certificate must match against the regular expression defined by the client_DNPattern variable.

Passing identity data

Once the certificate data has been validated, identity data must be established to allow the building of the assertion about the user. The configuration variable IdAttribute permits to configure which data is to be returned:

1. If set to any value, this value wil be used for extracting an attribute with that name from the subject DN of the certificate. If such attribute is not found in the subject DN, undef is returned.

2. If the variable is not set, the whole certificate subject DN is returned. This is the default.

FUNCTIONS