view release on metacpan or  search on metacpan

SecSess.pm  view on Meta::CPAN

	## don't perform in subrequests
	unless ($r->is_initial_req) { return OK; }

	$log->debug(ref($self), "->authz():");

	$req = $self->getRequirements($r);
	$resp = $self->authorizeRequest($r, $req);
	if (ref($resp)) {
		if ($msg = $resp->{message}) { $log->info($msg); }
		if ($resp->{forbidden}) { return FORBIDDEN; }
		unless ($resp->{uri}) { return SERVER_ERROR; }
		$r->header_out(Location => $resp->{uri});
		return REDIRECT;
	}
	return DECLINED;
}

## authenticate user & issue credentials
sub issue ($$) {
	my($self, $r) = @_;
	my $log = $r->log;
	my($resp, $msg);

	## don't perform in subrequests
	unless ($r->is_initial_req) { return OK; }

	$log->debug(ref($self), "->issue():");

	$resp = $self->verifyIdentity($r);
	if (ref($resp)) {
		if ($msg = $resp->{message}) { $log->info($msg); }
		if ($resp->{fill_form}) { return OK; }
		if ($resp->{auth_required}) { return AUTH_REQUIRED; }
		unless ($resp->{uri}) { return SERVER_ERROR; }
		$r->header_out(Location => $resp->{uri});
		return REDIRECT;
	}
	$resp = $self->issueCredentials($r);
	unless (ref($resp)) { $log->error($resp); return SERVER_ERROR; } 
	if ($msg = $resp->{message}) { $log->info($msg); }
	unless ($resp->{uri}) { return SERVER_ERROR; }
	$r->header_out(Location => $resp->{uri});
	return REDIRECT;
}

## renew credentials
sub renew ($$) {
	my($self, $r) = @_;
	my $log = $r->log;
	my($cred, $resp, $msg);

	## don't perform in subrequests
	unless ($r->is_initial_req) { return OK; }

	$log->debug(ref($self), "->renew():");

	$cred = $self->getCredentials($r);
	$resp = $self->validateCredentials($r, $cred);
	unless (ref($resp)) { $log->error($resp); return SERVER_ERROR; } 
	unless ($resp->{renew}) { # make sure credentials are sufficiently fresh
		$log->warn("Timeout before renewal."); # or replay attempt?
		if ($msg = $resp->{message}) { $log->info($msg); }
		unless ($resp->{uri}) { return SERVER_ERROR; }
		$r->header_out(Location => $resp->{uri});
		return REDIRECT;
	}
	$resp = $self->issueCredentials($r);
	unless (ref($resp)) { $log->error($resp); return SERVER_ERROR; } 
	if ($msg = $resp->{message}) { $log->info($msg); }
	unless ($resp->{uri}) { return SERVER_ERROR; }
	$r->header_out(Location => $resp->{uri});
	return REDIRECT;
}

## delete credentials
sub delete ($$) {
	my($self, $r) = @_;
	my $log = $r->log;
	my($resp, $msg);

	## don't perform in subrequests
	unless ($r->is_initial_req) { return OK; }

	$log->debug(ref($self), "->delete():");

	$resp = $self->deleteCredentials($r);
	unless (ref($resp)) { $log->error($resp); return SERVER_ERROR; } 
	if ($msg = $resp->{message}) { $log->info($msg); }
	return OK;
}

## change user ID (only for administrators)
sub changeid ($$) {
	my($self, $r) = @_;
	my $log = $r->log;
	my($cred, $resp, $msg, $uri, $uid);

	## don't perform in subrequests
	unless ($r->is_initial_req) { return OK; }

	$log->debug(ref($self), "->changeid():");

	## admin functions must be explicitly allowed in httpd.conf
	unless ($r->dir_config('SecSess::AllowRemoteAdmin') eq 'true') { 
		$log->error('Remote administration not permitted.');
		return FORBIDDEN;
	}

	## get credentials and validate them in usual way
	$cred = $self->getCredentials($r);
	$resp = $self->validateCredentials($r, $cred);
	if (ref($resp)) {
		if ($msg = $resp->{message}) { $log->info($msg); }
		unless ($resp->{uri}) { return SERVER_ERROR; }
		$r->header_out(Location => $resp->{uri});
		return REDIRECT;
	}

	## make sure request is consistent and comes from an administrator
	$resp = $self->verifyAdminRequest($r);
	unless (ref($resp)) { $log->error($resp); return SERVER_ERROR; } 

SecSess.pm  view on Meta::CPAN

SSLCipherSuite arguments.  At my site, I was surprised to find 
ALL:!ADH:!EXP:!EXP56 => 56 bits.

=head2 Cookie Domain Argument

  cookieDomain => <hashref>

The cookieDomain argument expects a hash reference of the form:

        { 'qop,authqop' => 'domain_string', ...  }

where 'domain_string' is literally the HTTP Set-Cookie domain string, and 
where the integers 'qop' and 'authqop' serve to define the session and 
authentication qualities of protections as described above.  A cookie will
be issued with the given domain and of the given strengths for each entry
in this hash.  The HTTP Set-Cookie secure flag is set if and only if 'qop' 
is nonzero.  As a convenient shorthand,

        int => 'domain_string'

is equivalent to

        'int,int' => 'domain_string'

Here are some examples taken from the demo.

      cookieDomain => {0 => '.acme.com', 40 => '.acme.com'}

will set two cookies for the .acme.com domain: a non-secure one of
form 'realm:0,0=value', and a secure one of form 'realm:40,40=value'.

      cookieDomain => {'0,40' => 'lysander.acme.com'}

will set a single non-secure cookie for the given host.  This is a
common paradigm for protecting passwords over an intranet.

      cookieDomain => {
        0 => '.acme.com',
        40 => '.acme.com',           # weak wildcard domain
        '64,128' => '.sec.acme.com', # stronger wildcard domain
        128 => 'milt.sec.acme.com'
      }

will set 4 cookies, all but the first being secure.  In addition to 
an explicit hostname at the end, this declaration defines two 
wildcard domains, *.acme.com supporting any export crippled, SSLv2
host, and *.sec.acme.com which intended to have a minimum of 64 bits 
throughout.

=head2 Session State URL Arguments

These have the obvious meaning and must agree in host, scheme, and
path with the corresponding Apache directives, as shown in the EXAMPLE 
section.  Generally for example,

authenURL => Where to go to get the appropriate credentials for a requested 
resource.

defaultURL => Where to go after logging in (if no initial request was made).

timeoutURL => Where to go to delete credentials.  Timeouts  and signouts 
are both sent here.

=head2 URL Chaining Arguments

  chainURLS => <arrayref>, issueURL => <string>

Apache::SecSess is designed to use cookies for most local authentication.  By 
their definition, cookies are restricted to a host, a DNS domain or subdomain.
The subclass Apache::SecSess::URL, which allows you to span authentication 
across DNS domains, requires additional arguments to accomplish this.   The 
argument chainURLS expects an array reference which defines a list of places 
to go for more (typically cookie) credentials.  For example,

      chainURLS => [
        'https://milt.sec.acme.com/authen', 
        'https://noam.acme.org/authen'
      ]

says that when URL credentials are issued, the client will be redirected
to each of the specified sites, in turn.  Each of these is expected to
be protected by a PerlAuthenHandler of type Apache::SecSess::Cookie::URL, 
which will issue local cookies.

The argument issueURL is used to tell the remote sites (listed in chainURLS 
arg) where to redirect the client back to, in order to continue chaining.

See the URL-Chaining example and the demo for more details.

=head2 Database Object Argument

 dbo => Apache::SecSess::DBI->new(
   dbifile => '/usr/local/apache/conf/private/dbilogin.txt'
 ),

UNFINISHED.  Apache::SecSess was designed to abstractly handle user
information.  All user ID, password, X.509 DN queries are handled through 
an opaque object of class Apache::SecSess::DBI.

Since there is no documentation for this version, you must follow the
instructions in INSTALL to get it to work.  Read db/* for more
info.

=head1 EXAMPLES

=head2 A Simple Cookie Example

Assuming all resources under directory /protected on one or more hosts
in a DNS domain need to be protected, place the following directive 
into 'httpd.conf':

  <Location /protected>
    SetHandler perl-script
    PerlHandler Apache::YourContentHandler
    PerlAuthenHandler $Acme::obj->authen
    require valid-user
  </Location>
  
On each such host, the secure session object $Acme::obj must be instantiated
from a 'startup.pl' file as in the following example, which uses an X.509
certificate for the original identification and authentication: